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Preface 



This document contains reference information for the D00 release version of CP-6 APL. 

The Los Angeles Development Center (L.A.D.C.) of Honeywell Information Systems, Inc. 
has developed Computer Aided Publications (CAP). CAP is an advanced text processing 
system providing automatic table of contents, automatic indexing, format control, 
automatic output of camera-ready masters, and other features. This manual is a 
product of CP— 6 CAP. with special handling for APL characters. 

Readers of this document may report errors or suggest changes through a STAR on the 
CP— 6 STARLCX? system. Prompt response is made to any STAR against a CP-6 manual, and 
changes will be incorporated into subsequent releases and/or revisions of the 
manuals. 

The information in this publicotlon is believed to be accurate in all respects. 
Honeywell Information Systems cannot assume responsibility for any consequences 
resulting from unauthorized use thereof. The information contained herein is subject 
to change. New editions of this publication may be issued to incorporate such 
changes. 



The information and specification in this document are subject to change 
without notice. Consult your Honeywell lylarlceting Representative for 
product or service availability. 

(c) Honeywell Information Sysstems Inc.. 1986 File No.:1W13 
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About This Manual 



This manual is organized in the following manner: 



Sect 



on 1 presents an overview of CP-6 APL, its features, capabilities, and 



compatibility with the CP-6 operating system. 
Section 2 describes the use of APL. 
Section 3 describes common elements of APL. 
Section 4 describes APL expression evaluation. 
Section 5 describes APL primitive functions. 
Section 6 describes APL statements. 
Section 7 describes APL defined functions. 

Section 8 describes system commands and APL workspace concepts. 
Section 9 describes APL report formatting. 
Section 10 describes APL execution stops. 

Section 11 describes system defined functions and variables. 

Section 12 describes APL file I/O. 

Section 13 describes APL I— D-S/II system functions. 

Section 14 describes system functions for manipulating packages. 

Section 15 describes functions and variables used in APL graphics. 

Section 16 describes blind I/O. 

Appendix A contains information on APL parameters. 
Appendix B contains o comprehensive list of APL symbols. 
Appendix C contains information on error messages. 

Appendix 0 contains information on APL's compatibility with CP-V workspace 
management, information on APL's compatibility with CP-V file input/output, and 
summarizes CP-V APL intrinsic functions. 



Appendix E contains o summary of CP-6 APL. 
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On-Line HELP Facility 



CP-6 APL has an on-line HELP facility. APL users can list syntax formats, 
parameters, and function or command descriptions at the terminal. For a list of HELP 
topics from the system level (i), enter: 



HELP (APL) TOPICS 
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Section 1 
Introduction 



APL is an acronym for A Programrning Language, the language created by Kenneth 
Iverson. It is a problem-solving language the symbology of which closely 
approximates mathematicol notation, making the language extremely attractive for use 
by engineers, financial planners, scientists, and statisticians. APL is an 
interpretive language designed for use on time-sharing computers. The term 
"interpretive language" means that APL does not wait to receive a complete program 
prior to compiling each statement into object code and executing it; instead APL 
interprets each statement as it is entered and immediately executes it. An answer is 
received by the user each time a portion of the total problem is stated. 

APL is a powerful language: concise in notation, easy to learn and easy to use. It 
has many features that make it attractive for use in business applications where user 
interaction and rapid feedback are key requirements. One of APL's major strengths is 
its ability to manipulate vectors and multi-dimensional arrays as easily as it does 
scalar (single) values. For example, a matrix addition that might require a number 
of statements ond several loops in other languages can be accomplished as A-i-6 in APL. 
It is this type of simplification which best exemplifies APL's concise power. 

This enhanced version of the processor is designed for operation under Control 
Program-6 and is hereafter referred to as CP-6 APL. This manual is intended 
primarily for use as a reference document by experienced APL programmers. Beginning 
APL users may find it useful to consult on APL primer to augment the information 
contained in this manual. Three such publications are "APL— An Interactive Approach" 
by Leonard Oilman and Allen J. Rose (John Wiley Sons, Inc., New York), "A Course in 
APL with Applications" by Louis D. Grey (Addi son-Wes I ey Publishing Company, Inc.. 
Reading. Mass), and "APL User's Guide" by Horry Katzan. Jr. (Van Nostrond and 
Reinhold Company, New York). 

CP-6 APL incorporates a broad range of improvements, including a number of 
improvements that ore unavailable on other APL systems. Some highlights of CP-6 APL 
include: 

o APL Standards Compatibility 

CP-6 APL is a superset of the ISO APL standard. 

o On-line and Batch Operation 

Complete flexibility of operation is provided. Programs may be developed and 
executed in any mode. The batch mode is advantageous for either long execution 
times or voluminous output. On— line mode is more advantageous for interactive 
program development and moderate amounts of execution time and output. 

o Operation from Terminals without APL Characters 

APL characters may be represented by combinations of alphanumeric and special 
characters in order to allow programs to be created or modified on any terminal 
supported by CP-6. 

o Input/Output Assignment Control 

The CP-6 APL system command. )SET, allows the assignment of normal and 'blind' 
I/O to files and devices such as line printers or magnetic tapes. It is also 
used to establish format control over printed output. 

o Formatted Output 

Three separate formatting functions are available (monadic v, dyadic *, and UFHT) 
to facilitate the preparation of reports and tables. 
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o File Input/Output 

A program-controlled mechanism is provided for file input/output. Any variable 
In an APL workspace may be written to a file and later retrieved for subsequent 
processing, permitting an APL program to operate on more data than can be 
contained in a workspace. APL entities may also be written as data records 
without their APL attributes, and non-APL records con be read. 

The CP-6 APL file I/O system operates with all CP-6 file types. File access may 
be with numeric keys or character keys. Files may be accessed in shared update 
mode, using the CP-6 Enqueue-Dequeue feature to coordinate shared access control. 

o Compound Statements 

More than one statement con be included on o line using diamonds for separation. 
Since an item of a compound statement can be a branch, this feature permits 
conditional execution control within a single statement of a function. 

o Blind Input/Output 

Blind input/output Is a form of device Input/output that permits input and output 
of character data. It is designed to facilitate the use of screen access modes, 
graphics terminols or other special devices with CP-6 APL. Using the )SET 
command, blind I/O may be used to create or access sequential files or to access 
devices such as line printers or magnetic tapes. 

o Easy Function Copying 

An entire function con be copied simply by changing the name of an already 
defined function. 

o RepI icate 

The / function has been extended to permit non— negative integers in the left 
argument. The selected items of the right argument ore "replicated" the number 
of times indicated in the left argument. 

o Powerful Function Editor 

CP-6 APL permits a range of lines to be specified for display or editing. Within 
the range specification, it is possible to request a display of all lines 
containing a string or identifier, or to replace all occurrences of a string with 
another string. 

o Enhancements to System Commands 

o The )SEAL command provides protected workspaces. When )SEAL is executed, the 
current workspace is saved with all user functions locked. A sealed 
workspace cannot be accessed by other users unless they are running APL. The 
workspace owner retains full access. 

o The )TERMINAL command allows independent setting of input and output terminal 
translation tables. 

o The Quiet commands OQLOAD, )QCOPY and )(IPC0PY) suppress the SAVED message 
when loading or copying successfully. 

0 Options have been added to the )SI command to control function suspension due 
to errors. 

0 The )COPY and )PCOPY commands allow system variables to be copied if named 
expl ici t ly . 

0 The )SIL command lists the lines in execution within the state indicator. 

o Availability of Other CP-6 Facilities 

A user of CP-6 APL may use other CP-6 processors such as EDIT, PCL, and FORTRAN 
from the same terminal during the same session. An APL workspace may pass 
commands to a command processor (e.g.. IBEX) and may link to other run units. 
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o The Execute Function 

The execute function has been extended to allow the execution of system commands. 

o Observation of Intermediate Results 

The )OBSERYE command permits the user to view intermediate results as APL 
executes a statement. 

o Single Stepping 

The )STEP command is used as a debugging aid. This command causes execution of 
one line of a defined function, and then immediately suspends execution. 

o Catching Assignments 

The )CATCH command is a debugging aid which permits the user to catch (or 
intercept momentarily) every assignment to a named variable immediately following 
each assignment. The assignment is "caught" by means of a function defined by 
the user according to their debugging requirements. 

o Error and Break Control 

CP-6 APL has a facility to provide the user with selective and dynamic control 
over errors and breaks. Since this facility permits bypassing of standard APL 
handling of breaks and errors, it is called the "sidetracking" capability. 

o Text Editing Functions 

Five system functions are available to facilitate the manipulation of character 
vectors in CP-6 APL. 

o Shared Variable System Functions 

Nine system functions are provided to support the sharing of variables between 
the workspaces of consenting CP-6 users. Any CP-6 user may access this facility. 

o Defined Function Extensions 

A dyadic defined function may be used monadically or dyodically. If used 
monadically. the dummy name that references the missing left argument will be 
undef ined. 

o Database Access 

System functions are provided to access I-D-S/II databases. All of the standard 
Codosy I DML functions are provided and they are augmented by unique information 
functions tailored to the APL environment. 

o Packages 

Packages provide the ability to manipulate aggregates containing variables and 
f unct ions. 

o Extended Error Messages 

Additional information concerning an error that APL has detected may be displayed 
with the )? command. 

o Nested Arrays 

Items of an array in CP-6 APL may themselves contain APL arrays. In addition to 
extending most existing functions to accept nested arrovs, new functions 
^enclose, disclose, equivalence, type, first, and depth) and a new operator 
(each) have been added. Defined functions, system functions, and derived 
functions are permitted as arguments to operators. 

o Vector Notation 

CP-6 APL syntax has been extended to provide a simple notation for the entry of 
nested arrays. 
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o Vector Assignment 

This mechanism is used to assign each item of a vector to a different name in o 
single operation. 

o Selective Assignment 

This capability allows items of an array that are selected by an APL expression 
to be assigned new values. 

o Sorting 

The grade-up and grade-down functions have been extended to sort character arrays 
and arrays of any rank. 

o Least Common Multiple Function 

The OR primitive function (v) has been extended to provide the Least Common 
Multiple function. 

o Greatest Common Divisor Function 

The And (a) primitive function has been extended to provide the Greatest Common 
Divisor function. 
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Section 2 
Using APL 



Logging On 



The user must first prepare the terminal for use. establish a connection with the 
CP-6 system, and then invoke the APL processor. This is done as follows: 

1. Connecting to the CP-6 system: 

a. Press the number 8 several times until CP-6 responds with: 
PLEASE TYPE A LEFT PARENTHESIS 

b. The system requests that the user enter a left parenthesis. Once a left 
parenthesis is entered, a salutation is printed after which the system 
requests a logon. At this time a valid logon should be entered. A logon 
consists of an account, name, and optional password, separated by commas. 
This information is not echoed (printed) on the terminal to provide privacy. 

*** CP-6 AT YOUR SERVICE, LADC L66A 
14:30 THU OCT 17 '85 LIVE 8(L6Kn-i*80 
LOGOH PLEASE: 

c. The CP-6 system will then allow the user to log on to the system with an 
attendant greeting, or inform the user of the reason for not logging on. 

d. When the CP-6 system prompts with !, the user is at the IBEX Command 
Processor level and may invoke APL by typing APL and pressing RETURN. 

Figure 2-1 shows a sample APL session including logon and logoff, as performed from a 
Diablo 1620 or equivalent terminal with an APL typewheel. 
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*** CP-6 AT YOUR SERVICE.LADC LBSB 
UiOO SAT MAY 22 *82 LINE 8(£6V//)-U80 
LOGON PLEASE : <E*>MYACCT , MYACNAME<E-> 

SYSIDx 12077 ON LADC L66£ AT liiiOOt 17. 71 SAT MAY 22 *82. 

lAPL 
APL C02 
CLEAR WS 

A*-tQ 
A 

12 3 4 5 6 7 8 

A^-OA 
99999999 

1 2 3 4 5 6 7 8 2 4 6 8 10 12 14 16 
)END 

IDI 

USERS » 37 
ETHF «= I 

90p RESPONSE < 50 WSrCS 
Wy(r 22 '82 1*:01 
I OFF 

CON'00i00tk9 £Jir-00:00:00:18 W-OO :00:01 . 15 PHME' 147 CHG' .00 



Figure 2—1. Sample APL Session 



General APL Input 

The following paragraphs define the 
input/output characteristics. 



APL character set, APL names, and various 



Character Set 



One of CP— 6 APL's unique characteristics is the richness of its character set. An 
APL keyboard normally has 94 printing graphics. AM of these are legal characters. 
In addition, backspacing may be used to create the following overstrikes, all of 
which ore legal characters: 



Other legal characters are blank (the space bar), tab (the TAB key, treated as one or 
more blanks), and carriage return (the RETURN key). Two other characters are also 
accepted for control purposes: the <CTL-D> sequence and the BREAK key discussed 
below under "Line Corrections during Input" and "Control Keys". 
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Names 



Names are used to identify certain CP-6 APL constructs. All variables, functions, 
groups, workspaces, and statement labels have names; the following restrictions apply 
to these names: 

1. All names except workspace names can contain from 1 to 79 characters. Workspace 
names can contain from 1 to 31 characters (see Section 8). 

2. Names may be composed of letters, numbers, L, underlined letters, underlined A, 
and underscore. 

3. Names cannot begin with a number or underscore. 

4. There can be no blanks embedded within a name. 

5. A particular kind of name, called a distinguished name, begins with □. 
Some examples of names are: 

4 tAlBQLL BLl SI 234 TEMPERATURE UPW 



User Input versus Computer Output 



The user can enter input whenever the carrier or cursor is indented six spaces from 
the left margin. As soon as the user has typed any input and pressed the RETURN key, 
APL takes control. Characters entered by the user while APL is processing will be 
"stored" until APL has completed processing the previous input, printed any results, 
and prompted for more input (usually by indenting six spaces from the left margin). 

User input and computer output are easily distinguished. Computer output usually 
begins at the left margin while user input is usually indented six spaces. For 
example: 

)DIGITS 2 

WAS 10 

3^9 

0.33 

2+2 

k 

**2 

2 

Everything at the left margin in this example is printed by APL, while everything 
which is indented is typed by the user. 



Line Corrections during input 



A line can be corrected during input as long as the RETURN key has not been struck. 
Simply strike the RUBOUT key, to delete characters up to the error and enter <ESC> R 
to retype the correct portion of the line. Then proceed with the entry of the line. 
For example, suppose the user mistakenly types 30-20 instead of 30+20. The user can 
correct this as follows: 

30-20\\\<«> enter three RUBOUTS and <ESO R 

30+20 the system displays 30; user enters +20 

50 system responds with 50. 
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Perhaps the simplest I ine correct ion method is to delete oil of the input with the 
control X character. Another correction method can be employed if the user discovers 
that a character has been omitted. As long as the RETURN key has not been struck, 
the user can simply backspace to where the character is to be inserted (or enter 
<ESC> V followed by the character at which to position), enter <ESC> J, and type it. 
For example, suppose the user types the following line and notices that one left 
parenthesis is missing: 

(lOff)*2) + (20i/)*2 

By simply backspacing and typing the required left parenthesis, the user can enter 
((10i/)*2)+(20i/)*2 

This illustrates that it is not always necessary to enter characters in order. The 
user can leave blanks in a line, then backspace and fill them in. As a rule, APL 
interprets what the user sees at the terminal; this is known as visual fidelity. For 
more information on standard CP-6 input line editing, see the CP-6 Programmer 
Reference Manual (CE40). 



Execution and Definition Modes 



From the user's viewpoint, CP-6 APL operates in two modes, execution mode and 
definition mode. In execution mode, the processor responds to each line of input by 
taking a specified action or by performing requested calculations and printing a 
result. In the following printout, for example, the first line is a system command 
that causes the processor to take some action and to respond with a message, and the 
third line (3^9) performs a calculation, printing the results on the fourth line: 

)DIGITS 2 

WAS 10 

3*9 

0.33 

System commands con be entered during execution or definition mode. Calculations are 
performed only in execution mode. 

In definition mode, statements (that is, calculations) are saved as part of a defined 
function instead of being executed immediately. System commands issued in this mode, 
however, ore executed immediately. After functions are defined, they can be 
referenced in other defined functions or in statements entered in execution mode. 
The user must type the del symbol V to begin definition mode, and another V to return 
to execution mode. See section 7 under Defined Functions, for a detailed description 
of definition mode. 



Prompts 



CP-6 APL has four ways of prompting for (that is, requesting) input: direct line 
prompt, function line prompt, evaluated input prompt, and quote-quad prompt. These 
are described below. 
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Direct-Line Prompt 



When APL is ready for user input rn inunediate execution mode, it automatically moves 
six spaces in from the left margin. This is a signal to the user to enter a 
statement or system command. Direct-line prompts are shown in the following example: 

2+2 

4*2 

2 

In this example, APL indented six spaces to prompt for user input, and the user 
entered the statement 2+2. The processor then printed the result of the calculation 
at the left margin, moved to the next line, and again indented six spaces to prompt 
for more input. 



Function-Line Prompt 



Within definition mode (that is. when a function Is being defined) CP-6 APL prompts 
for user input by printing a line number in brackets at the left margin. After 
printing the line number, it moves three spaces to the right and waits for user 
input. As on example, look at the following portion of a function definition: 

VSQUARE 

(21 

In this example, the user entered a function header {^SQUARE) , and APL typed the [1] 
and moved three spaces to the right to prompt for user input. The user then entered 
the statement A^(.B»B), and APL typed the [2] to prompt for more user input. This 
continues until the user ends the function definition with another del symbol V. 



Quad Prompt 



The quad symbol □ can be used in a statement to indicate evaluated input. When APL 
encounters the quad on execution of the statement, it halts and requests input by 
printing the symbols □: , moving to the next line, and indenting six spaces. The user 
can enter any valid APL expression. This expression will be evaluated, and its value 
substituted for the quad contained in the statement. Execution of the statement then 
resumes. Examples of the quod prompt are shown below: 

□ : 

7x2x4 
A 

7 

ANSWER*U 

'YES' 
ANSWER 

YES 
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Quote-Quad Prompt 



The quote-quad symbol Q (a quote symbol overstruck with o quod) is used to enter 
character data. It is executed similarly to the quad symbol except that nothing is 
printed to signal the user, and no six-space indentation takes place. The user 
enters character data without enclosing it in quotes. For example: 

YES 

Al 

YES 



Comments 



Comments can be written on separate lines or can follow (that is, be tacked onto) 
statements. They may be included on any line except a system command line or a 
function edit control line. To enter o comment, type the symbol o ond follow it with 
the comment. This symbol is produced by typing a n symbol (upper shift C) and 
overstriking it with o o symbol (upper shift J). Any valid APL characters may appear 
to the right of the a symbol. The a and any characters to the right ore ignored in 
APL expression evaluation, but will be printed if the line is displayed. Examples of 
comments are shown below: 

a THIS IS A COMMENT. 

A.<-B*B nSET A = B-SQUARED. 

[3] jC^-r+S a COMMENT t X IS SET TO r+5 



Control Keys 

The BREAK key is used to interrupt execution or stop a lengthy display on the 
termi no I . 



Statements and System Commands 

Each completed line of input in CP-6 APL is classified as either a statement or a 
system command. Statements specify the operations to be performed by APL, such as 
calculations, branching, and assignments of values or expressions. Some examples of 
statements are: 

4+2 
Bt-A'irZ 
■*-START 
VA PLUS B 
[3] 'ENTER VALUES FOR A* 

System commands are used to communicate directly with the APL system itself. They 
ore concerned primarily with the mechanical aspects of the processor, such as logging 
on and off, saving, loading, and deleting workspaces. System commands always begin 
with a right parenthesis. A few examples of system commands follow: 

)SAVE NEW JOB 
)LOAD OLD JOB 
)END 
)DIGITS 

Statements and system commands ore described in detail in sections 6 and 8, 
respect ively. 
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Variables and Functions 



Data (numeric or character) can be assigned a name and stored in the active 
workspace. The name and the associated value are collectively known as a variable. 
The value may be a single data item (scalar) or a group of data items (array), and 
may be changed as needed during the course of a program. Examples of assignments of 
variables ore shown below: 

A*-5 

B2*l 2 3 

Some character symbols indicate that basic APL operations, such as addition or 
multiplication, are to be performed. These symbols are called primitive functions. 
Functions can be monadic (have one argument) or dyadic (have two arguments). Some 
examples of functions are: 

X 

+ 

r 



The domain and range of function arguments and a list of all the functions are 
presented in Section 3 under Primitive Functions. Section 5 is devoted to a detailed 
discussion of each function. 



Defined Functions 



In addition to the primitive functions, APL permits users to define new functions, 
name them, and store them in a workspace. Defined functions can then be referenced 
by name in subsequent statements, either as programs by themselves or as mathematical 
operations used in a formula. To define a function, the user enters it statement by 
statement while APL is in definition mode. This mode begins when the user types a 
del symbol v and ends when another v is typed. 
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Section 3 

Common Elements in APL 



Constants 



Constants are either numeric or character. 



Numeric Constants 



Numeric constants con take the form of integer or real numbers. An integer is a 
whole number, requiring neither decimal point nor exponential form. A real number is 
a number, usually with a decimal point, expressed in either exponential form or 
decimal form. The user need not generally be concerned with whether a number is 
integer or real, or exponential or decimal, since APL automatically takes care of any 
necessary conversions. The representation of numeric data is accomplished with the 
following characters: 

0123*56789. "£• 

The numbers ore the ordinary keyboard digits, and the decimal point is the keyboard 
period. The ~ character, called the negative sign, is found over the digit 2 on an 
APL keyboard and is used to indicate negative numbers. It should be distinguished 
from the - character, which is found over the + symbol and is used for subtraction. 
The negative sign is only valid for numeric constants; it is not valid in any other 
context. The is the letter E on the keyboard and is used to indicate on exponent. 
Embedded blanks, commas, and other punctuation ore not allowed in APL numbers. 

APL ignores leading and trailing zeros, so that the user need enter only the ports of 
numbers required for calculations. Thus, there is no need for the user to enter data 
as all integer or all fractional. For example, the number one may be entered as 
1.00, 001.0, 1, etc. Examples of numeric constants entered in decimal form ore shown 
be I ow: 

5 + 5.55 

10.55 

6.8 -s- 20 

0.34 

The negative symbol (~) can be used only with a numeric constant to indicate a 
negative number; it can never be used with a name. The symbol immediately precedes 
the applicable number; that is, no blanks are allowed between the symbol and the 
number. The use of the negative symbol is shown below: 

"2 

"2 

"4 4- "5 

'9 

* - "3 

7 

It is often easier to enter very large numbers in exponential form rather than 
decimal form. Exponential representation is written as a number, followed by E, 
followed by an integer indicating a power of 10. (£ can be interpreted as "times 10 
to the following power".) The exponent (the number following the E) can be o 
positive or negative number. Following are some examples of numeric data in 
exponential form: 
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APL Exponential Notation 



iylathemat ical Notation 



14 



"8.37ri* 



-8.37 



X 



10 



-6 



4.2 



X 



10 



5 



.99E5 



.99 



X 



10 



-60 



3.8r~60 



3.8 



X 



10 



The maximum and minimum magnitude representable numbers in CP-6 APL are 
approximately: 

8.37987g956ri52 

4.661462957r"156 

Note that non-integer values are handled internally as "double precision floating 
point" numbers. Fractions that ore representable exactly in decimal notation, such 
as .1. ore not exactly representable in this internal form. In some instances, this 
will cause results of operations to deviate from expected results, particularly if 
the anticipated result is displayed to 20 decimal places or is a value near zero. 



Character Constants 



Character constants ore enclosed in quote symbols and con contain any keyboard 
character including legal overstrikes and the space character. The quote symbols are 
used to distinguish a character constant from a number, the name of something, or a 
constant in the language. They ore not printed in the display of the literal. For 
exomp I e : 



In this example, the name A has been assigned the value of a character constant. 



Vector Notation 



When two or more values appear together separated by one or more blanks, a vector is 
formed. The vector that is formed has the properties of length (the number of 
items), type (numeric, character or nested), and rank (vector). Some examples of 
numeric vectors are: 

113 

1 2.5 "726ri2 

Character vectors may be formed either as a series of character scalars with each 
item enclosed in quotes, or by enclosing the entire string in quotes. For example: 

IJft 1/1 I I t7<f 1^1 l£l tgt 1£1 

HI THERE 

*HI THERE' 
HI THERE 

Both character vectors are equivalent. If a quote is to be used within text, it must 
be represented by two quotes. The use of the quote character is shown below: 

A^*THE ••i>»» CHARACTER IS USED FOR COMMENTS.* 
A 

THE CHARACTER IS USED FOR COMMENTS. 



A 
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Character arrays may be generated, compared for equality. Indexed and catenated just 
like any other arrays. 

A character constant may contain one or more carriage returns. If a carriage return 
is entered before the closing quote is given, APL wi 1 1 automatically type the closing 
quote at the beginning of the next line to indicate that a closing quote is required 
to end this string. If the constant is to be extended, a RUBOUT may be entered to 
delete the closing quote. 

Parentheses may also be used to separate items in vector notation. For example: 
A^il) (2) 

The three examples above ore all equivalent ways of forming the two item vector 1 2. 
Multiple blanks and extra parenthesis are also always permitted: 

A^19 20 

il"^((19)) ( ( ( 20 ) ) ) 

The use of parenthesis in vector notation is used to produce a single item out of any 
array that they enclose. The parenthesis may also enclose any array. For example: 

A^i'YEARn 1983 (^SALES') (2619 5250) 
A[3] 

SALES 

In this example, vector notation has produced a four item vector which contains the 
vector 'YEAR* as the first item, the scalar 1983 os the second item, the vector 
'SALES* as the third item, and the numeric vector 2619 5250 as the final item. 
Parentheses ore not required around character vectors because the enclosing quotes 
are already grouping them. For example: 

A^'YEAR' 1983 ^SALES' (2619 5250) 

This example produces the same four item vector as the previous example. 



Names 



All of the following constituents of the APL language hove names (sometimes known as 
identifiers) so that they may be easily referenced: variables, functions, groups, 
statement labels, and workspaces. 



Name Format 



A name can include only letters, the letters underscored, digits. L, 4. and _ 
characters. A name cannot start with a digit or on underscore. Distinguished names 
follow the other rules for names, but always start with a single □ character. 

Lengths of names may vary, depending on their use. The names of variables, 
functions, groups, and statement labels can be of any length up to 79 characters. 
Workspace names (also known as fids in CP-6 APL) con be up to 31 characters in 
length. 
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fiame Usage 



The uses of APL names are described below: 

1. A variable refers to the name given to scalar or array values by the assignment 
symbol (the character '«■*) described later in this section under Assignment. 

2. Defined function names are treated briefly later in this section under Function 
References, and in detail in Section 7. Defined Functions. 

3. A collection of names can be referenced using groups. Included in the group can 
be the names of variables, functions, and other groups (see the )GRP command in 
Sect ion 8) . 

4. A label is given to o statement within a user-defined function so that it may be 
referenced by other statements of that function. Statement labels are used as 
branch reference points. 

5. A workspace name is used to Identify on active workspace so that it can be saved 
and later recalled. Workspace names are referenced in system commands which are 
described in Section 8 (also see item 8). 

6. A password is assigned to a workspace or file to prevent other users from 
accessing it. The password must always be used in order to access the workspace 
or file. Passwords are described in Section 8 (also see item 8, below). 
Passwords may contain any characters. 

7. An account is the identifier of a recognized user's account. The account must be 
specified when logging on to the CP-6 system and when accessing a workspace or 
file in another user's account. The use of accounts is described in Section 8 
(also see item 8. next). Accounts may be. but are not restricted to. letters or 
digi ts. 

8. In CP-6 APL, a saved workspace is a CP-6 file. A file identifier (fid) refers to 
the information needed in a system command to save a workspace or to reference it 
after it has been saved. A file identifier takes the following form: 

workspace[ . [acct][ . [password]]] 

where 

workspace is the name assigned to the workspace, or file. It can consist of 
up to 31 characters from the set A-Z, A~Zt ~» Si _i ti and 0-9. 

acct is the identifier of a recognized user's account. It con consists of up 
to eight characters from the set of accounts authorized by the installation 
manager. 

password is assigned to a workspace, or file, in order to restrict user 
access. It can consist of up to eight characters. 

The bracketed items in the above form indicate optional items. File identifiers 
are used in the following system commands, all of which are described in Section 
8: )LIB» )COPY, )DROP, )LOAD, )PCOPY, )QCOPY, )QLOAD, )QPCOPY, )SAVE, )SET, and 
)WSID. 

Accounts and Passwords may include any characters except the period, comma, 
semicolon, or embedded blanks. 

For further information on file identifiers, see the the documentation on the 
command processor IBEX in the CP-6 Programmer Reference Manual (CE40). Set nomes 
and serial numbers are also discussed there. 
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Var iables 



A variable must be assigned a value before it can be used. The value assigned can be 
numeric, character, or nested and can be a scalar or an array (a vector, a matrix, or 
a higher-order array). The user can display the value of a variable at any time 
simply by typing the variable name. Examples of the assignment and use of variables 
ore shown below: 

B^Z 3 k 5 
A+B 
* 5 6 7 

5pt20 

C 

12 3 4 5 
6 7 8 9 10 
11 12 13 U 15 
16 17 18 19 20 
D^B^Z 
D 

1 1.5 2 2.5 

A variable con be respecified at any time simply by assigning a new value to the 
variable name. The most recent value specification replaces any previous value. For 
example, notice the following: 

ABC*- 1 

ABC^O 12 3 4 5 
0 12 3 4 5 
ABC*Z 

ABC^O 12 3 4 5 
0 2 4 6 8 10 

In this example, ABC is first assigned a value of 1 and calculations are performed 
with that value. The variable ABC Is then assigned a value of 2 and the calculations 
are performed using this new value. 

Another way of respecifying a variable value is to decrease or increase its value by 
a certain amount. For example, suppose variable A has a value of A has a value of 2 
and the user want to increase this value by 1. This can be accomplished as follows: 

A* An 
A 

3 

Notice that the calculation 2-t-l is performed first, and then the result 3 is assigned 
to 0 variable A. This type of operation is particularly useful for setting up a 
counter to test the number of occurrences of an event, such as the number of passes 
through a program loop. Each time through the loop the counter can be increased or 
decreased by 1 and then tested against a desired value to determine further action. 



Local and Global Variables 



Local variables exist while user-defined functions (Section 7) are active, that is, 
while the function is pendent or suspended. Local varlobles, described below, are 
classified os follows: 

o Dummies 
o Result 
o Loca I s 
o Lobe 1 8 

Dummies, result, and locals ore indicated by their presence In the header of a 
defined function. Labels are Indicated on statements within a defined function. 
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At o given point in time if a variable is not local, it is global. It is possible 
(in fact useful) to allow global variables to be identified by the same name as local 
variables (or local variables for one function to use the same name as local 
variables for another function). This concept is useful in APL because it allows a 
defined function to be formed without regard to name conflicts. Its local variables 
are totally independent of any previously assigned variables. Furthermore, if the 
function calls itself, a new set of variables exist independent of the original local 
variables. As each such function call exits (that is, becomes inactive again), the 
current set of local variables disappear and the earlier values associated with their 
names once more become accessible. 

Wlhen a function call occurs, its local variables are said to "shadow" previous 
definitions for the names used by the local variables. Shadowing can be repeated 
extensively as functions are called. As these functions exit, their shadowing effect 
is removed. Only globals will exist when no function is active. Global variables 
also exist if their names are not shadowed by any currently active functions (for 
example, the local variables use unique names).. Shadowing is illustrated in Figure 
3-1. 



Local Variables 



The following local variables are named in a function header: result, dummies, and 
locals. These are all optional; a function is not required to use any local 
variables. Notice the following example: 

7R4-r F XiAiB'.C 

In this example, the function F names the following local variables in its header 

line: 

R (result) - note that R is followed by a symbol, which designates that R is the 
result name. 

X (dummy) - one name to the right of F separated by blanks(s), designates the right 
dummy. When F is called, the right argument's value is automatically assigned to 
local variable X. 

Y (dummy) - one name to the left of F, separated by blank(s), designates the left 
dummy. When F is called, the left argument's value is automatically assigned to 
local variable Y. 

A, B, and C (locals) - note that each local name is preceded by a semicolon. 

The remaining type of local variable is the label. Its name appears in a function 
line as in the example below. 

[31 L-.a THIS LINE IS LABELED. 

Notice that the label's name, L, follows the line number, [3], and is in turn 
followed by a colon. Although labels are classified as local variables, it is more 
appropriate to consider them local constants. They cannot be assigned values; that 
is, the following expression is a syntax error when L is a label: 

L^H 

The value of a label is the line number of its function line (which cannot change 
during execution of the function). 

The example in Table 3-1 illustrates the effect of shadowing as functions Fl and F2 
become active and inactive. 
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Table 


3—1. Effect of Shadowing 


Examp 


le 






Descr ipt ion 




) CLEAR 








CLEAR 


IfS 










V*-* V'GLOBAL' 






Set V, W, X, Y 




V** W'GLOBAL* 






to be global variables. 




X^' X'GLOBAL* 








Y<-'Y'GLOBAL* 










V FliXiY 








[1] 


• Fl CALLED • 








[21 


V 








[3] 


V 






Define Fl , naming X and 


Ik] 


,X*-* X'LOCAL (fl)* 






Y as its locals. 


[5] 


,Y*-'Y'LOCAL (ri)' 








[6] 


F2 fl CALL FZ 








[71 


• f 1 EXITS 'V 










^FZtWiX 








[11 


' FZ CALLED • 








[2] 


V 








[31 


,W*-'W'LOCAL (r2)' 






Define F2, naming W 


[4] 


,X^' X'LOCAL (FZ)* 






and X as its locals. 


[51 


Y 








[61 


• FZ EXITS 'V 










V V X Y 






Verify V, W, X, Y. 


V^GLOBAL W'GLOBAL X'GLOBAL 


Y'GLOBAL 




FZ 






Call F2. 




FZ CALLED 








V 'GLOBAL 








V'LOCAL (F2) 






V and Y ore still global. 


X'LOCAL {FZ) 






W and X ore local to F2. 


Y'GLOBAL 










.FZ EXITS 










V W X Y 








V'GLOBAL W'GLOBAL X'GLOBAL 


Y'GLOBAL 


V, W , X, Y ore global again. 




Fl 






Ca 1 1 Fl . 




Fl CALLED 








V 'GLOBAL 








W'GLOBAL 






V and w are still globol. 


X'LOCAL IFl) 






X and Y are local to Fl . 


Y'LOCAL (Fl) 










FZ CALLED 






F1 calls F2. 


V 'GLOBAL 








W'LOCAL iF2) 






V is st i 1 1 g 1 obo 1 . 


X'LOCAL (FZ) 






W and X ore local to F2. 


Y'LOCAL (Fl) 






Y is sti 1 1 local to Fl . 




FZ EXITS 










Fl EXITS 










V W X Y 






V, W, X, Y are again global. 


V'GLOBAL W'GLOBAL X'GLOBAL 


Y'GLOBAL 
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Arrays and Indexing 



As mentioned earlier, a variable may represent a scalar or an array. A scalar is 
always a single item, an item being a character, number, or nested array. One 
example of a scalar is: 

SCLR 

33 

Although an array may be made up of more than one item, it can also consist of a 
single item or even no items. An array with no items is called an empty array. 

In addition, arrays can be classified as vectors, matrices, or higher-order arrays. 
A vector is an array of one dimension, and is displayed as a collection of items 
arranged on one line. As a typical example, notice the vector named VECT which has 
four items: 

VECT^b 7 9 11 
VECT 
5 7 9 11 

A matrix is an array with two dimensions, (a dimension is sometimes called a 
coordinate) and is displayed as a collection of items arranged in o rectangular 
pattern. An example of a two-dimensional matrix, named HAT, is shown below: 

MAT 

12 3 4 5 
6 7 8 9 10 
11 12 13 U 15 

Notice that this matrix has three rows and five columns. It is two-dimensional 
because it is made up of rows and columns. 

A higher-order array is an array with three or more dimensions, displayed as a 
collection of items in a set of rectangular patterns. An example of a higher-order 
array is: 

CUBE 

12 3 4 5 

6 7 8 9 10 

11 12 13 U 15 



16 17 18 19 20 
21 22 23 24 25 
26 27 28 29 30 

This higher— order array is three-dimensional. It has two planes, and each plane has 
three rows and five columns. 

The user can find out if a variable is a scalar, a vector, a matrix, or a 
higher-order array by using pp to test for the rank (that is, number of dimensions) 
of the variable. For example, testing the previous variables SCLR, VECT, HAT, and 
CUBE wi 1 1 give 

ppSCLR 

0 

fipVECT 

1 

ppHAT 

2 

ppCUBE 

3 

A 0 indicates a scalar, a 1 indicates a vector, a 2 indicates a two-dimensional 
array, a 3 indicates a three-dimensional array, and so on, up to a maximum of 62 
dimensions. 
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The user can also determine the size of each dimension in an array (that is, the 
"shape" of the array) by using p. For example, testing the same variables SCLR, VECT, 
HAT. and CUBE wi II give 

pSCLR 
pVECT 

k 

pHAT 

3 5 

pCUBE 

2 3 5 

Since a scalar has no dimensions, p of a scalar produces an empty (vector) result; 
nothing is displayed (other than the next input prompt). The above example confirms 
that SCLR is a scalar (no dimension); that VECT Is a vector with four items; that MAT 
is a two-dimensional matrix with three rows and five columns (15 items); and that 
CUBE is a three-dimensional array with two planes, each with three rows and five 
columns. One other situation should be noted, p of on empty vector will return the 
value zero, and p of an empty array will return one or more zeros depending on which 
dimension or dimensions have length zero. 



Indexing of Arrays 



Items in an array con be referenced by their positions within the array. The 
position number is called an index. The index can also be used for several items, 
and to index other indexed arguments. The following topics are discussed in this 
subsect ion: 

o Referencing a Single Item 
o Referencing More Than One Item 
o Assigning a Value to an Array 
o Indexing an Indexed Argument 



Referencing a Single Item 

An item in an array is referenced by its position within the array, which is 
indicated by one or more numbers called indexes. One number is used as the index of 
on item in a vector array; two numbers, as the index of on item in a two-dimensional 
matrix; three numbers, as the index of on item in o three— dimensional array; and so 
on, with one number for each dimension. 

The indexes of oil arrays start with 0 or 1 , depending on the index origin. When the 
user first enters APL, the index origin is 1 by default. It con be set to 0 by 
assigning the QlO system variable to 0, and reset to 1 by reassigning the QlO 
variable to 1 . 

V<-'ABCDE* 

VIZ] 

B 

VIZ] 

C 

Vll] 

B 

□/0<-l 

The indexes of a two— dimensional matrix also start with 0 or 1 , depending on the 
index origin, but two numbers are used in each index. The first number selects the 
items from a row, and the second number selects the items from a column. The indexes 
ore ordered with the rightmost position varying the fastest, then the next rightmost, 
and so on. For purposes of illustration, consider the matrix named HATdt 

MAT2 

3 1 U 2 12 

13 15 4 8 14 

6 10 7 9 5 
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The indexes for this matrix, with index origin 1, will be 

[1;1] [1;!;] [1:3] ll-.k] [1;5] 
[2{n (2;2] (2i3] [2:4] (2;5] 
[3;1] [3;2] [3|3] [3;«] (3;5] 

Thus HAT3[lil] Is 3; MAT3[l;Z] is 1; HATZ[li3] is 11; MAT3ll;ii] is 2; end so on. 
Notice that semicolons must be used to separate the numbers of each dimension. 

An item in an array of more than two dimensions is selected in the same way as an 
item of a two-dimensional array, except that more numbers are included in the index. 
An index contains one number for each coordinate of the associated array. For 
example, consider the following three-dimensional array: 

MATk 
I H Ik 1 
15 13 2 8 

11 12 6 16 
5 3 9 10 

To reference the value 8 in this array, one uses the index MATkll i2;k] , where 1 
denotes the first plane, 2 denotes the second row. and 4 denotes the fourth column. 
Notice that each additional coordinate always adds a number to the beginning of on 
index. The rightmost number of an index always refers to a column; the next 
rightmost to a row; the next rightmost to a plane; the next to o panel of planes; and 
80 on. 



Referencing More Than One Item 

To reference items within an array, simply include the index of each desired item in 
brackets after the array name. For example, notice the following vector: 

il*5 * "1 3 9 "2 7 4 

To select the items 5, ~1, and 3 from this vector (ossuming an index origin of 1), 
one uses the expression All 3 4] as shown here: 

il[l 3 k} 

5 "1 3 

Other examples of referencing several items in vector A ore shown below. Notice in 
the second example that indexing con be used to create larger and differently shaped 
arrays: 

il[l 1 8 8 8] 
5 5 4 4 4 

A13 2pl 3 4 2 6 5] 

5 "1 
3 4 
'2 9 

There are a variety of ways to reference several items in a matrix. Consider the 
fol lowing matrix: 

HAT5 

1 10 9 8 11 

2 15 4 5 6 
15 3 12 13 7 

Examples of referencing several items in this matrix are shown below. These examples 
assume an index origin of 1. 

Afiir5[l:4 5 2] 
8 11 10 

MAT511 2;] 

1 10 9 8 11 

2 15 4 5 6 

ff^7'5[l 2|1 2 3 4 5] 
1 10 9 8 11 
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2 15 4 S 6 

MAT511 2 3{^] 

8 5 13 

MATbil 2ik 5] 

8 11 
5 6 

MAT5l;Z 41 

10 8 
15 5 
3 13 

HAT511 2 3;2 41 

10 8 

15 5 
3 13 

In fact, the shape of the indexing result has a rank equal to the shape of each of 
the index expressions joined together. If an index expression is elided, the result 
shape has the length of the elided coordinate inserted. 

Several items in a three-dimensional array are referenced similarly to a matrix, 
except that the third coordinate must also be added to the index. Consider the 
following three-dimensional orray: 

MAT 6 
I 2 2 k 5 
6 7 8 9 10 

11 12 13 U 15 

16 17 IB 19 20 

Examples of referencing several items in this array are shown 
below. These examples assume an index origin of 1. 

MAT6[l;2i5] 



10 










MAT61 ;2; 1 


6 


7 


8 9 10 


16 


17 


18 19 20 






Miir6[:2;l 31 


6 


8 




16 


18 








MAT611 1 2:1 


1 


2 




6 


7 


9 


1 


2 




1 


2 




6 


7 


9 


1 


2 


4 


11 


12 




16 


17 


19 


11 


12 


U 



Assigning a Value into on Array 

One or more items in on already existing orray can be assigned values via the 
assignment symbol The user simply places the variable name and the index 
designation to the left of the symbol, and the new value to the right. Examples 
follow, all of which assume on index origin of 1. 

Example of vector: 
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V 

4 5 6 7 8 9 10 11 12 13 
Vll 3 5]<-l 0 1 
V 

1 5 0 7 1 9 10 11 12 13 
V[l 3 5 7 91*0 
V 

0507090 11 0 13 
VHOOPS^Vl 14-2 
V 

2222222222 
2 

Example of matrix: 

MAT7*-Z 5ptl0 

HAn 
12 3 4 5 
6 7 8 9 10 

Wiir7(2j5J<-0 

MAT7 
12 3 4 5 
6 7 8 9 0 

/fi(r7tl 2j3 51*"1 

MAT! 

1 2 "1 4 "1 
6 7 "I 9 "1 

W>ir7(;j4-2 
MAT7 

2 2 2 2 2 
2 2 2 2 2 

Notice from examples above iHAT6[ -,2',] , V[]'*-2, and MATTl'.HZ) that if on Index 
position is not filled, all index values for that position are assumed to be 
applicable. Assigning a new value to on indexed variable does not change the rank or 
shape of the variable, it merely changes some items in the variable. 

The value that is assigned to a variable or indexed variable is also the "result" of 
the assignment. This is illustrated by the example WHOOPS-f-VD^Z. Since V is a 
10-item vector, all 10 index values received the value 2. But the result as far as 
the assignment operation is concerned is the scalar 2. Thus. WHOOPS becomes a scalar 
variable having the value 2. When analyzing APL expressions, it is helpful to 
Imagine that assignments are "invisible". For example, 

3+/fC{*J<-5 

can be analyzed as if the assignment were not present, i.e., 

3+ 5 
making the result (8) apparent. 



Indexing an Indexed Argument 

In APL. an indexed argument may itself be indexed. For example: 
All'.MZ] 

which is equivalent to the expression (>l[l:])[2] and is interpreted as follows. 
Obtain the first row of matrix 4. This row temporarily forms a vector, call it T, 
whose length is the number of columns originally given for A. Select the second item 
from vector f, and (in this case) display the value of that item. 

Only arguments can be followed by multiple indexes. Specifications and coordinates 
cannot; thus the following is a syntax error: 

A[ii][Z]-*-X 
LI If ESC AN ERR a 
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The user instead is advised in this case to use 



Functions and Arguments 

APL expressions are derived from three fundamental entities: operators, functions, 
and values. Functions may be formed by the user (see section 7 under Defined 
Functions) or are included as on inherent part of the language. In the latter case, 
they ore called primitive functions. Most primitive functions ore represented by a 
single character. A general treatment of these functions Is given in this section; 
for 0 detailed treatment, see Section 5, APL Functions. 

Operators usually take APL functions as arguments and return a new (or derived) 
function. The derived function typically applies the function arguments to the value 
arguments in an operator defined order. Examples of APL operators Include axis, 
inner product, and outer product. 

Values ore APL arrays and have certoin attributes: type, rank, depth, and length or 
shape. The domain of on array may be character type, numeric type, or nested type. 
There ore three numeric domains: logical, integer, or real; however, the user seldom 
needs to be concerned with this distinction. Logical data represents 1*s or O's and 
is stored in bit form. Integer data represents positive and negative numbers (using 
neither decimal point nor exponential form) whose range is limited to the size of one 
computer word. Real data is stored in doubleword form (that is, in floating-point 
form). Text or character data is stored in byte form. The nested domain type can 
hove an array item which contains other APL arrays or both character and numeric data 
items. If a numeric argument contains numbers that could fit in more than one 
domain, it is made to uniformly contain numbers in the largest size domain necessary. 
Thus the following vector argument has integer domain since that is necessary to 
represent the 2: 

10 10 2 

The rank of on array is the number of its dimensions (or coordinates). A scalar has 
a rank of zero, a vector has a rank of one, a matrix has a rank of two. and so forth. 
The maximum allowed rank in CP-6 APL is 62. 

The length of a vector is its number of items or components (zero for on empty 
vector). The shape or dimension of an array (including a vector) is on ordered 
vector containing the lengths of its coordinates. Single-item vectors and 
single— item arrays of higher order (for instance, o 1 1 1 reshape of 5 is a 
single-item three-dimensional array) are not equivalent to scalers but may be used 
interchangeably with scalers in many operotions. Vectors and arrays of higher ranks 
may also be 'empty'. This is the cose when the length of a coordinate is zero. 

The depth of an array indicates the maximum level of nesting of items within the 
array. A simple scalar character or number has depth 0. An array containing only 
simple scalar character or scalar numeric items has depth 1. An array containing 
items of depth 0 and 1 has depth 2. In general, on array containing items of depth 
less than or equal to N has o depth of N4-1 . Simple arrays have depth 0 or 1 . Nested 
arrays have depth 2 or more. 

Functions ore classified as monadic or dyadic according to the number of their 
arguments. A monadic function has one argument to the right of the function. A 
dyadic function has two arguments, one to the right of the function and one to the 
left. 

In many cases, the same function can be used both monodicolly and dyadical ly, but the 
resulting functions are different, olthough usually related in a natural way. Each 
function has Its own domain, rank, and length or shape requirements, and the result 
of a function may have a new set of these characteristics. 
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Axis Operator 



Certain functions are coord! note— dependent . For example, a matrix rotation can occur 
about the first coordinate (rotation of rows) or about the second coordinate 
(rotation of columns). For such functions, the user has the option of specifying 
this coordinate in the form of a bracketed expression to the right of the function. 
The value of this expression must be an integer of appropriate range. These 
coordinate specifications are called the Axis operator. The Axis operator takes the 
coordinate specified and the function to its left and creates a new "derived" 
function which operates on the requested coordinate. The following functions may use 
a coordinate specification: 

Reduction Compression Enclose 
Reversal Expansion Disclose 
Rotation Catenation 
Scan 

NOTE: Catenation may also use a fractional coordinate specification. This form of 
catenation is called lamindtion. Enclose and disclose permit the 
specification of a vector of axes. 



APL Functions and Operators 

Tables 3-2, 3-3, and 3—4 include summary information about Scalar Functions, Mixed 
Functions and Operators, respectively. Each table lists dyadic and monadic 
operations, if any, and gives simple examples. For a detailed description of these 
functions and operators, see Section 5. 



Scalar Function Sunrvnary 



Scalar functions are pervasive. That is, when they ore applied to nested arrays, the 
function is applied to every numeric and every character scalar in the array. 



Table 3-2. Scalar Functions 


Function 


Usage 


+ 


Monadic — Conjugate: 

Leaves argument unchanged. Example: 
*10 

10 

Dyadic - Addition: 

Adds two arguments. Example: 
104-20 

30 
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Table 3-2. Scalar Functions (cent.) 


Funct ion 


Usage 




Monadic - Minus: 

Negates the argument that follows it. Example: 
-(10+5) 

"15 

Dyadic — Subtraction: 

Subtracts the right argument from the left argument. 
Examp 1 e : 

10-5 

5 


X 


Monadic - Signum: 

Returns ~1, 0, or 1, depending on whether its argument is 
negative, zero or positive. Example: 

x"15 

"1 

Dyadic - Multiplication: 

Multiplies the left argument by the right argument. 
Examp 1 e : 

10x15 150 
150 1500 




Monadic - Reciprocal: 

Divides 1 by the value of its argument. Example: 

•i-1 3 5 

1 0.3333333333 0.2 

Note that this is equivalent to the dyadic use: 

1*1 3 5. 

Dyadic - Division: 

Divides the left argument by the right argument. 
Examp i e : 

10*5 2 1 .5 

2 5 10 20 
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Table 3-2. Scalar Functions (cont.) 


Funct ion 


Usage 


* 


Monadic - Exponential: 

Raises e (i.e., the base of the natural logarithms, 
having the value of approximately 2.71828...) to the 
power of its argument. Examples: 

*l 

2.718281828 

*10 
22026. ((65?9 

*2.2 
9.025013^99 

Dyadic - Exponentiation: 

Raises the left argument to the power indicated by the 
right argument. Examples: 

10 10 2*2 10 3 
100 IflO 8 




Monadic - Natural logarithm: 

Computes the natural logarithm of its argument (that is. 
log base e of the argument). Examples: 

• 1 

0 

92 

0.693H71806 
«3 10 

1.098612289 2.302585093 

Dyadic - Logarithm: 

Computes the logarithm of the right argument to the base 
indicated by the left argument; that is. computes the 
power to which the left argument must be raised to equal 
the right argument. Examples: 

109100 

2 

1091 10 100 1000 
0 12 3 

294 

2 

291 2 4 8 

0 12 3 


I 


Monadic - Floor: 

Returns the greatest integer less or equal to its 
arguments. Examples: 

I 10.7 

10 

12 4.1 "8.9 "2 
2 4 "9 "2 
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Table 3-2. Scalar Functions (cent.) 


Funct ion 


Usage 




Oyodic - Minirnum: 

Compares two arguments and returns the value of the 
smaller argument. Examples: 

5L2 

2 

913 11 8 

3 9 8 

li 3 213 

3 3 2 


r 


Monadic — Cei 1 ing: 

Returns the least integer greater than or equal to its 
argument. Examples: 

r 10.7 

11 

r 2 "8.9 "2 
2 5 "8 "2 

Dyadic - Maximum: 

Compares two arguments and returns the value of the 
larger argument. Examples: 

512 

5 

9r3 11 8 ~2 10 
9 11 9 9 10 


1 


Monadic - Absolute value: 

Returns the absolute value of its argument. Example: 

no 

10 

Dyadic - Residue: 

Returns the remainder from dividing the right argument by 
the left argument. Examples: 

2U 

0 

5115 16 17 18 

0 12 3 

2 317 

1 1 
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Table 3-2. Scalar Functions (cont.) 


Funct ion 


Usage 


t 


Monadic - Generalized factorial: 

For integer arguments, returns the factorial of its 
argument. The argument may not be a negative integer. 
(See Section 5 for explanation of ! with non-integer 
argument.) Examples: 

!3 

6 

!0 1 2 

112 

Dyadic - Generalized combination: 

For positive integer arguments, the right argument 
represents a population size and the left argument 
represents a sample size. The result Is the number of 
different samples that can be drawn from the population 
(see Section 5 for explanation of ! with non-integer 
arguments.) Examples: 

13!52 
6.350135596ril 
2!10 

45 

3! 10 

120 


0 


Monadic — Pi times: 

Multiplies the value of pi (approximately 
3.14159265353589793) times its argument. Examples: 

01 

3.U1592654 
02 .1 

6.283185307 0.314159265(1 

Dyadic - Circular: 

Returns the result of any of a number of trigonometric 
functions. The left argument specifies the trigonometric 
function and must be one of the integers from —7 to 7, as 
foil ows : 

e {1-Ji:*2)*0.5 

1 sine X -1 arcsine X 

2 cosine X -2 arccos X 

3 tangent X -3 orctan X 

4 (l+;i:*2)*0.5 -4 Sx(i-B*-2)*0.5 

5 sinh X -5 orcsinh X 

6 cosh X -6 orccosh X 
1 tonh X -7 arctanh X 

Examples: 

20(10x2.5) 
0.9912028119 
102 k 

0.9092974268 "0.7568024953 
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Table 3-2. Scalar Functions (cent.) 


Funct ion 


Usage 


< 


Dyadic - Less than: 

Tests if the left argument is less than the right 
argument. Returns 1 if the test is true, and 0 if the 
test is false. (See Section 5 for effect of comparison 
tolerance on relational functions.) Examples: 

2<3 

1 

3<* I 2 5 
10 0 1 




Dyadic - Less than or equal to: 

Tests if the left argument is less than or equal to the 
right argument. Returns 1 if the test is true, and 0 if 
the test is false. (See Section 5 for effect of 
comparison tolerance on relational functions.) Examples: 

1 

2^1 2 3 4 
0 111 


> 


Dyadic - Greater than: 

Tests if the left argument is greater than the right 
argument. Returns 1 if the test is true, and 0 if the 
test is false. (See Section 5 for effect of comparison 
tolerance on relational functions.) Examples: 

2>3 

0 

2>"2 0 2 3 
110 0 




Dyadic - Greater than or equal to: 

Tests if the left argument is greater than or equal to 
the right argument. Returns 1 if the test is true, and 0 
If the test is false. Examples: 

223 

0 

2i"2 0 2 3 
1110 
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Table 3-2. Scalar Functions (cent.) 


Funct ion 


Usage 




Dyadic - Equal to: 

Tests if the left argument is equal to the right 
argument. Returns 1 if the test is true, and 0 if the 
test is false. (See Section 5 for effect of comparison 
tolerance on relational functions.) Examples: 

0 

2»0 I 2 3 
0 0 10 

^''CANADA* 
0 10 10 1 




Dyadic - Not equal: 

Tests if the left and right arguments are unequal. 
Returns 1 if the test is true, and 0 if the test is 
false. (See Section 5 for effect of comparison tolerance 
on relational functions.) Examples: 

1 

3i«~3 0 3 6 
110 1 

'A'^'CANADA* 
10 10 10 


A 


Dyadic - And: 

(The arguments must be 0 or 1.) Returns 1 if both 
arguments are 1, and 0 for any other combination of 
arguments. Examples: 

OAO 

0 

(1-2)A(3<4) 

0 

(1<2)A3<1 

0 

(1»1)A3<* 

1 

Least Common Multiple: 

Returns the least common multiple of the left and right 
arguments. The LCM of a set of numbers is defined as 
their product divided by the CCD of the numbers. 
Examples: 

3A2 

6 
12 

0.5A0.3 

1.5 
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Table 3-2. Scalar Functions (cent.) 


Funct ion 


Usage 


V 


Dyadic - Or: 

Returns 1 if either or both arguments are 1. and 0 if 
neither argument is 1. Examples: 

Ovl 

I 

(l=2)v(4<3) 

0 

(3<*)v4<5 

I 

Greatest Common Divisor: 

Returns the greatest common divisor of the left and right 
arguments. The CCD of a pair of numbers is defined as 
the largest divisor of both which produces on integer or 
near-integer result. Examples: 

.5v-=-3 
0.1666666667 
2v8 

2 

2v3 

I 


A 


Dyadic - Nand: 

Returns 0 if both arguments are 1, and 1 for ail other 
combinations. Examples: 

0*0 

I 

(2<1)A(5<1) 

I 

(1<2)*(1<5) 

0 


V 


Dyadic - Nor: 

Returns 1 if both arguments are 0. and returns 0 for all 
other combinations. Examples: 

OvO 

1 

Ovl 

0 

(l-2)v(2<l) 

1 

(l-2)*v2<3 

0 
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Table 3-2. Scalar Functions (cent.) 


Funct ion 


Usage 




Dyadic - Not: 

Returns 0 if the argument is 1, and returns a 1 if the 
argument is 0. Examples: 

-0 I 

1 u 

~(6>4) 

0 

-10 10 
0 10 1 



Mixed Function Sunrunary 

The mixed functions produce results with a structure that is different from that of 
its arguments. Mixed functions con be sub-divided into the structural mixed 
functions and the transformation mixed functions: 

0 The structural mixed function subset re-orders the array right argument under the 
optional control of a left argument. The re— ordering is generally dependent on 
the right argument's rank and shape but independent of the actual elements within 
it. 

o The transformation mixed functions produce results which typically depend upon 
the value of the array arguments. 



The following table is a summary of APL mixed functions. 



Table 3-3. Mixed Functions 


Funct ion 


Usage 


t 


Monadic - Index generator: 

Generates o vector whose length is the value of the 
argument. If the index origin (Q/O) is 1, the vector 
will contain positive integers 1 through value of the 
argument. If the index origin is 0, the vector will 
contain the positive integers 0 through the value of the 
argument minus 1. Examples: 

tS 

1 2 3 <i 5 

□70*0 
15 

0 12 3 4 

□70*1 

Dyadic - Index of: 

Returns the position of the right argument in the left 
argument. If the right argument is not found in the left 
argument, it is given a value of the last index position 
of the left argument plus 1. Examples: 
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Table 3-3. Mixed Functions (cont.) 


Funct i on 


Usage 




6 4 3t6 

I 

6 4 3t3 5 4 

3 4 2 


t 


Monadic - Ravei: 

Generates a vector from either a scalar or an array of 
higher dimension. Examples: 

12 3 4 
5 6 7 8 
,A 

12 3 4 5 6 7 8 

Dyadic - Catenation: 

Joins together scalers or arrays of conforming dimension. 
Examples: 

Af-l 2 3 
B*-ii 5 6 7 
A.B 

12 3 4 5 6 7 

(C*2),Cx3-2 

1.5 3 


P 


Monadic — Shape: 

Returns an empty vector if the argument is a scalar, the 
length (or number of items) if the argument is a vector, 
or a vector containing the length of each dimension if 
the argument is a higher-order array. Examples: 

pA^2 

pfl^l 5 6 7 

4 

pC<-3 3pi9 

3 3 

PPit 

0 

Dyadic - Reshape (restructure): 

Generates an array whose dimensions are the left 
arguments and whose items are token from the right 
argument. Examples: 

5pl 

11111 

2 4p8 
8 8 8 8 
8 8 8 8 

2 4pt8 
12 3 4 
5 6 7 8 
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Table 3-3. Mixed Functions (cont.) 


Funct ion 


Usage 


i 


Monadic - Grade-up: 

Ranks the components of its argument in ascending order, 
and returns tlie positions (i.e., indexes of the 
components). Example: 

A"-! k I 2 2 I 
U 

13 6 4 5 2 

Dyadic - Grade-up: 

Ranks the components of its right argument in ascending 
order defined by the collating sequence given by the left 
argument. Similar to the monadic grade-up function 
except that both arguments must be character and the 
ordering is defined by the left argument. Examples: 

il*3 kp'ABRACODEBACK' 
'ABCDEFGHIJK'iA 

1 3 2 


t 


Monad i c - G r ade-down : 

Similar to Grade-up. except that it returns the indexes 
in descending order. Examples: 

A^l k I 2 2 I 
fA 

2 5k 136 

Dyadic - Grade-down: 

Ranks the components of its right argument in the 
descending order defined by the collating sequence given 
by the left argument. This is similar to the monadic 
grade-down function except that both arguments must be 
character and the ordering is defined by the left 
argument. Examples: 

A'*-2 kp'ABRACODEBACK* 
'ABCDEFGHIJK'iA 

2 3 1 


? 


Monadic - Rol 1 : 

Returns an integer pseudorandom ly selected from t B. 
Examples: 

?5 

3 

?3 3 3 

3 2 1 

?5 8 11 13 

2 5 8 2 

Note that this function is modified by QIO (index 
origin) . 
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Table 3-3. Mixed Functions (cont.) 


Funct i on 


Usage 




Dyadic - Deol : 

Returns the number of integers specified in the left 
argument, each pseudorandomly selected from the integers 
specified in the right argument, and with no repetition 
of numbers in the result. Examples: 

8 3 4 2 
I 2 Z k 

Note that this function is modified by 0/0 (index 
or igi n) . 


i 


Dyadic - Base value: 

Switches from one number system to another. The right 
argument contains the numbers to be converted and the 
left argument contains the increments needed to convert 
from one unit to another. The left argument, usually 
called the radix vector, can be thought of as the base of 
the number system. Examples: 

10 10 1015 6 5 

565 

0 60110 20 

620 

2 2 2 211 0 0 1 

9 

2il 0 0 1 

9 


T 


Dyadic - Encode: 

Converts a number to some predetermined representation. 
It works in reverse of the base value operation above. 
The following shows how to reconvert to the initial 
arguments used above in the base value. Examples: 

10 10 10T565 

5 6 5 

0 60T620 

10 20 

2 2 2 2Tg 
10 0 1 


V 


Monadic - Format: 

Converts numeric arrays to character arrays. The result 
is the same as if the argument were printed. Examples: 

V 3 3.1 

3 3.1 
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Table 3-3. Mixed Functions (cont.) 


Funct ion 


Usage 




Dyadic - Formot: 

Converts numeric arrays to character arrays while 
controlling the format with the left argument. The left 
argument specifies the width and precision to be used in 
the display of the right argument. Examples: 

2 0V3 5 

3 k 5 

5 2" 3 0.61 5.5 
3.00 0.61 5.50 


t 


Monadic - First 

Returns an array whose value is the first item of the 
right argument. If the right argument is empty, then the 
result is the prototype of the right argument. 

For a scalar right argument, this function is the inverse 
of the enclose function. Examples: 

4110 

1 

i'ONE* *TWO* *THREE' 

ONE 

Dyadic - Take: 

Selects the number of components indicated by the left 
argument from the right argument. If the left argument 
is positive, the take function selects the components 
from the beginning of the right argument. If the left 
argument is negative, the take function selects the 
components from the end of the right argument. Examples: 

A-t-2 4 6 8 
34>| 

2 <l 6 
4 6 8 


* 


Dyadic - Drop: 

Similar to take except that the indicated items are 
dropped instead of selected. Examples: 

A^Z H 6 B 
2*A 

6 8 

~UA 

2 4 6 
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Table 3-3. Mixed Functions (cont.) 


Funct i on 


Usage 


c 


Monadic - Type: 

Returns an array containing 0 where argument items are 
numeric or blank where argument items are text. Example: 

«1 'BRUCE' 2 (3 4) 
0 0 0 0 

• •=«! *HI* 2 

0 110 

Dyadic - Membership: 

Returns 1 if a given item of the left argument is on item 
of the right argument, and 0 if it is not. The result 
has the same dimensions as the left argument. Examples: 

^••■16 

B«A 
1110 

C'*-*ABCDEFGHIJK' 
D<-3 3p* HOWAREYOU' 

1 0 0 
1 0 1 
0 0 0 




Monadic - Execute: 

Treats its argument (a character scalar or vector) as an 
APL statement. Examples: 

5 


c 


Monadic - Enclose: 

Increases the depth of the argument by 1 and decreases 
the rank. If an axis is not specified, all axes are 
enclosed and the result is a scalar. When an axis is 
specified, the rank of the result is the rank of the 
argument minus the number of axes being enclosed. 

The enclose of a simple scalar yields the scalar 
unchanged. Examples: 

c»5' 

B 

VENICE 

c[n3 3pi9 
123 <»56 789 
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Table 3-3. Mixed Functions (cont.) 


Funct ion 


Usage 


3 


Monadic — Disclose: 

Decreases the depth of the argument by 1 and increases 
the rank. If the axes are not specified, the new axes 
ore inserted after the last axis of the argument. 

The disclose of a simple array yields the array 
unchanged. Examples: 

HI 
2 

p[>3(l 2) (3 k 5) 

1 2 0 
3 4 5 

2 3 

Dyadic - Pick: 

Select an item from the right argument specified by the 
path indices in the left argument. Each item of the left 
argument must be a simple scalar or vector of integer 
indices which selects on item to be indexed by the next 
item of the left argument. Example: 

2 97 8 9 

8 

2 i (2 1)3 1 ( ( 2 2p3 4 5 6) 7) 8 

5 
9 




Monadic - Depth: 

Returns a simple non-negative integer scalar indicating 
the maximum depth of nesting in the right argument. 

A simple scalar number or character has depth 0. Arrays 
containing simple scalar numbers or characters have depth 
1. Examples: 

0 

-12 3 

1 

-•ilfiC* (4 (5 6)) 7 

3 

Dyadic - Equivalence: 

Returns a simple logical scalar. The result is 1 if the 
left argument is identical to the right argument, 
otherwise the result is 0. 

Arrays are identical if they have the same shape and the 
same values in all corresponding positions. Eriipty arrays 
are Identical only if their prototypes are identical. 
Ex amp 1 es : 
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Table 3—3. Mixed Functions (cont.) 


Funct ion 


Usage 




' APPLE' APPLE* 

1 

0 

9«,9 

0 
0 


S 


Monadic - Matrix Inverse: 

Used to invert matrices. Examples: 

A^3 3p4 2 "5 5 "4 4 2 2 "20 

□PP4-2 

BA 

0.17 0.072 "0.029 
0.26 "0.17 "0.099 
0.0*3 "0.0097 "0.063 

Dyadic - Matrix Divide: 

Used for solving systems of linear equations. Examples: 

A 

5 "4 k 
2 2 "20 

5'«-22 "7 80 

B^A 
1 "1 "* 


0 


Monadic — Transpose: 

Performs row column tronsposition on its matrix argument. 
Examples: 

A 

1 2 3 5 
6 7 8 9 10 
11 12 13 U 15 
QA 

1 6 11 

2 7 12 

3 8 13 

4 9 U 

5 10 15 

Dyadic - Transpose: 

Returns an array similor to the right argument except 
that the coordinates fdimensions) are changed according 
to the left argument (that is, the left argument 
specifies the new position of the original coordinates). 
Examples: 

B'*-2 l^ 2pt2k 
2 1 3Qfi 
1 2 3 
13 U 15 
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Table 3-3. Mixed Functions (cont.) 


Funct ion 


Usage 




4 5 6 
16 17 18 

7 8 9 
19 20 21 

10 11 12 
22 23 24 




Monadic - Reversal: 

Reverses the order of the components of a vector, or the 
components of each each row of a matrix. Examples: 

il^l 2 4 6 
Oil 
6 4 2 1 

5 4 3 2 1 

Dyadic - Rotation: 

Rotates the items in the right argument as specified by 
the left argument (i.e. according to the number of places 
specified in the left argument). Examples: 

i|4-l 2 4 6 

lOA 
2 4 6 1 

2U 
4 6 12 


e 


Monadic - Reversal along the first coordinate: 

Same as 0 above except along the first coordinate instead 
of the last. This is equivalent to OtQ/Ol. Example: 

D*-MAT<-3 4ptl2 
12 3 4 
5 6 7 8 
9 10 11 12 

BMAT 
9 10 11 12 
5 6 7 8 
12 3 4 

Dyadic - Rototion along the first coordinate: 

Same as 0 above, except along the first coordinate 
instead of the last. This is equivalent to 
Examples: 

[}*-MAT*-Z 4ptl2 
12 3 4 
5 6 7 8 
9 10 11 12 

IQMAT 
5 6 7 8 
9 10 11 12 
12 3 4 
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APL operators usually take functions (primitive, system, or user-defined) and produce 
a derived function which is then applied to array arguments. The manner in which the 
function argument is applied to the array arguments distinguishes the various 
operators. 

The letters f and g in the following table represent any functions. 



Table 3-4. Operotors 



Funct ion 



Usoge 



f/ 



Monadic 



Reduct ion: 

Inserts the APL function specified to the left of the / 
between each item of the right argument, performs the 
operation from right to left, and returns a value with 
one less coordinate than the right argument. Examples: 







+/1 2 


3 <( 5 


15 




-/I 2 


3 4 5 


3 






4ptl2 


I 


2 


3 4 




5 


6 


7 8 




9 


10 


11 12 
+/V 




10 


26 


42 
-/H 




"2 


"2 


"2 





Dyadic - Compression and Replicate: 



Suppresses some items of a vector and retains others. 
Items of the right argument corresponding to a 1 in the 
left argument are retained while those corresponding to a 
0 are dropped. If either argument contains just one 
item, it applies to all items of the other arguments. 
Examples: 



i4<-5 7 9 11 

1 0 1 1/il 

5 9 11 

1 0 1 1/S 

|>«i<r<-3 4pil2 
12 3 4 
5 6 7 8 
9 10 11 12 

1 0 1 0/Wiir 

1 3 
5 7 
9 11 



Replicate is like compression but this function will 
replicate items as well as suppress. In this case, the 
left argument is an integer vector, whose items are 
greater than or equal to zero. Each item of the left 
argument indicates the number of times the corresponding 
item in the right argument is to be replicated. 
Exompl es: 
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Table 3-4. Operators (cont.) 


Funct ion 


Usage 




2/ 'APPLE' 
AAPPPPLLEE 

1 2 3/'W0W' 

WOOWWW 

2 1 O/'ITS' 

IIT 


f/ 


Monadic - Reduction along the first coordinate: 

Same as f/ above except reduction occurs along the first 
coordinate rather than the last (equivalent to f/lQlO]. 
Examples: 

U*-H'*-3 'ipil2 
I Z 3 k 
5 6 7 8 
9 10 11 12 

15 18 21 2k 

5 6 7 8 

Dyadic - Compression along the first coordinate: 

Some as above except that compression or replication is 
along the the first coordinate instead of the last. 
Equivalent to /(Q/O}. Examples: 

Q*-MAT^2 kptl2 
12 3 4 
5 6 7 8 
g 10 11 12 

0 1 0/HAT 
5 6 7 8 


f.g 


Dyadic - Generalized inner product: 

This operator is a generalized form of the inner product 
of matrix multiplication. The particular form that 
corresponds to traditional matrix multiplication is 
A+.*B, where the second dimension of matrix A is the same 
OS the first dimension of B. The result has the some 
first dimension as A and the some second dimension as B. 

. In the conventional matrix inner product, each item of 
the result is the sum of products of items from A and B 
(see Section 5 for detailed description). The APL 
generalized inner product allows different forms such as 
the sum of equality tests, the maximum of sums, etc. 
Examples: 

A<-2 3pt6 
5<-3 2p-t6 
A 

1 2 3 
4 5 6 

B 

"1 '2 
"3 "* 
"5 "6 

A+.*B 
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Table 3-4. Operators (cont.) 


Funct ion 


Usage 




"22 "28 
"49 "64 

0 0 
0 0 

At.+B 

0 "1 
3 2 

The general form is Ai .gB where f and g represent any 
function. A and B may be vectors, matrices, or higher 
order arrays, subject to conf ormabi 1 i ty rules described 
in Section 5. 


o.f 


Dyadic - Generalized outer product: 

This operator is a genero li zat i on of matrix outer 
product, Ao.xB. The conventional form multiplies each 
item of A by each item of B. The shape of the result is 
the catenation of the shapes of A and B. In the 
generalized form, multiplication may be replaced by any 
APL function. Examples: 

Ao.*A 
0 12 3 4 
12 3 4 5 

2 3 4 5 6 

3 4 5 6 7 

4 5 6 7 8 

Ao.xA 
0 0 0 0 0 
0 12 3 4 
0 2 4 6 8 
0 3 6 9 12 
0 4 8 12 16 

Ao.<A 
0 1111 
0 0 111 
0 0 0 1 1 
0 0 0 0 1 
0 0 0 0 0 


f\ 


Monadic - Scan: 

Returns value of same shape as argument. For vectors, 
the 1'th result item is formed by taking the first i 
argument items, placing f between them, and evaluating 
right to left. For example: 

+\l 3 5 7 9 
1 4 9 16 25 

-\3 1 1 5 
3 2 3 "2 

A coordinate specification IK] may be used; if omitted, 
the last coordinate is assumed. 

+\[i]2 3pi6 

1 2 3 
5 7 9 
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Table 3—4. Operators (cont.) 


Funct ion 


Usage 




Dyadic - Expansion: 

Inserts additional items into an array. For each 0 in 
the left argument, a prototype item (blank for character, 
zero for numeric) is inserted in the result, which 
otherwise is the same as the right argument. Examples: 

A^l 2 3 1* 

B*-'ABCD' 

1 0 1 0 1 0 
1 0 2 0 3 0 4 

10 10 10 l\B 
A B C D 

CH-w<-3 'ipCMvtes+tiEj 

ABCD 
EFGH 
IJKL 

1 0 1 0 1 0 1\W 
ABCD 
EFGH 
IJKL 




Monadic - Scan along the first coordinates: 
Same as f\[D/0]. Thus, as above, 
+V2 3pt6 

1 2 3 
5 7 9 

Dyadic - Expansion along the first coordinate: 

Same as \ above, except expansion occurs along the first 
coordinate rather than the last. This is equivalent to 
\[D/(7I. Example: 

|>W<-3 *pD/IK[65+il21 

ABCD 
EFGH 
IJKL 

1 0 1 0 1\W 

ABCD 
EFGH 
IJKL 


f" 


Monadic - Each: 

Returns a value of the same shape as the argument. Each 
item of the result is formed by applying the monadic 
function to the corresponding item of the right argument. 
Examples: 

p"*ABC' 'HAPPY' 

3 5 

t"2 3 
12 12 3 

^"*XYZ' 'HOOD' 
ZYX DOOM 
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Table 3-4. Operators (cent.) 



Funct ion 



Usage 



Dyadic - Each: 



Returns a value of the same shape as the left and right 
arguments (o singleton argument is extended to the shape 
of the higher ranked argument). 

Each item of the result is formed by applying the dyadic 
function to the corresponding items of the left and right 
argument. Examples: 

Zq"'ABC' 'HAPPY* 

AB HA 

W'BCA* (14) 
CAB 2 3 <i 1 



Defined Function References 

Defined functions are used in much the some way as primitive functions, but defined 
functions must first be formed by the user instead of being an inherent part of the 
language. Once a defined function hos been formed, or "defined", it is referenced by 
its assigned name. (Naming conventions are described earlier in this section under 
Names.) A general discussion of functions is given in this section; for a detailed 
discussion, see Section 7, Defined Functions. 

Like primitive functions, defined functions can have arguments which in turn have 
attributes of domain, rank, length, and shape (see Functions and Arguments above). 
Functions are classified as monadic, dyadic, or ni Iodic, according to their number of 
arguments. A monadic function has one argument to the right of the function name. A 
dyadic function may have one or two arguments, one to the right of the function name 
and one optionally to the left. A ni Iodic function has no arguments; the function 
name is referenced by itself. 

The right argument is the value of the largest, complete APL expression immediately 
to the right of a function. For the example below. F \s a function whose right 
argument is 2+t3. 

(f 2+i3) 'POUHDS' 

In this case, the character vector 'POUtfDS' is not included in the argument since the 
parenthesis splits the example into two distinct expressions. 

The left argument is the value of the smallest complete APL expression to the left of 
a function. In the example below, D la a dyadic function whose left argument is 
(13). 

2+ (i3) D 4 



In this case, the parenthetical expression (t3) is the smallest complete APL 
expression immediately to the left of D. 2-*-(t3) is also an APL expression, but it is 
larger. Therefore, the above example is interpreted as 

2+resul t 

where "result" is the result supplied by the function reference 
(13) D 4 

In addition, any of the classes of defined functions may specify on implicit or 
explicit result. Thus there are actually six types of defined functions: monadic, 
dyadic, and ni Iodic each of which may optionally produce a result. 
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The class is determined by the way a function is defined (thot is, the function 
header), and it affects the way a function is referenced in on expression. Defined 
functions with explicit results may appear in compound expressions, much like 
primitive functions. Defined functions without results may appear alone; they cannot 
appear in compound expressions except as the last function to be executed. 

A defined function may reference itself; that is, it may be recursive. A recursive 
function is one that references itself in the process of its execution. 

When a function is invoked, it may complete execution and return a result or it may 
become suspended or pendent during execution. A suspended function is one in which 
execution has been stopped before completion (the reasons for stopping execution are 
given under Suspending Execution in Section 7). A pendent function is usually one 
that has referenced o suspended function and Is unable to complete execution because 
of the suspended function. Suspended functions are always stopped "between" lines, 
but a pendent function is stopped in the process of executing a line. A function can 
be both suspended (stopped at some point) and pendent (in execution at some point). 
For instance, if a recursive function is stopped after it colls itself, it is 
suspended (at the stop) and pendent (where it called itself). 



Assignment 

The following paragraphs define simple assignment, multiple assignment, and indexed 
assignments. 



Simple Assignment 

The assignment symbol, denoted by a I ef t— poi nt i ng arrow, is used to assign values to 
named variables or to a system variable. (Some programmers may refer to this symbol 
OS the specification symbol or the replacement symbol, but the term assignment symbol 
is used throughout this manual.) It is the assignment that causes a variable to be a 
scalar, a vector, a matrix, or a higher—order array. The assignment of a value or an 
expression to a quad displays the value. Examples of assignments are shown below: 

Assigns the value of the expression 5^2*k to variable A. 
^4-12 3 4 5 

Indlcotes that B Is to be a vector with the values 1, 2, 3, 4, and 5. 

Another way of assigning the numbers 1 through 5 to variable B. (Assuming an index 
origin of 1 .) 

Indlcotes that C Is to be a matrix (with two rows and four columns) and that it is to 
be made up of the values 1 through 8 (assuming an Index origin of 1), as shown here: 

12 3 4 
5 6 7 8 

1)4-2 3p5 6 1 2 8 9 

Indicates that D is to be a matrix (with two rows and three columns) and that It Is 
to be made up of the values 5, 6, 1, 2, 8, and 9, as shown here: 

5 6 1 
2 8 9 

Indicates that the value of D Is assigned to E. 
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Multiple Assignments 



APL allows repeated use of assignment, or multiple assignments, in a single 
statement. Examples of multiple assignment are shown as follows: 

A,B 

5 6 6 

X.Y,Z 

5 7 9 

U*-C<-2 3*5 
2 2 k 5 



Vector Assignment 

This notation may be used to assign each item of a vector to a name in a list of 
names. In this cose, the specification symbol (^) is preceded by the list of names 
enclosed in parentheses. The specification symbol must be followed by an APL 
expression which produces a vector having the same length as the number of names. 

Examples: 

iA B C)<-1 2 3 
A 0 B f> C 

1 
2 
3 

iHAHE ADDRESS)*'JOE WHO' '21 CENTURY BLVD. LOS ANGELES' 

NAME 
JOE WHO 

pn*-ADDRESS 
21 CENTURY BLVD, LOS ANGELES 
28 



Indexed Assignment 

One or more items of on already established array may be assigned new values. This 
is done by placing the variable name and the index des i gnat i on(s) to the left of the 
assignment symbol, and the new value(s) to the right, as shown below (these examples 
all assume an index origin of 1): 

Q*-A^i 5*32 
15 4 3 2 

All 21^2 3 
A 

2 3 4 3 2 

Al]<-0 
A 

0 0 0 0 0 

i>5<-2 3pi6 

12 3 
4 5 6 

BlliZl^k 
B 

14 3 
4 5 6 

Bin*o 

B 

0 0 0 
0 0 0 
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Selective Assignment 



This operotion permits selected elements of a named array to be given new values 
while leaving the shape and the unselected elements unchanged. Bracket indexing or 
use of the selection functions are used to select the array elements to be changed. 
The selection functions that ore used with selective specification ore ravel 
monadic ,). reshape (monadic p), take (dyadic *), drop (i). first (t), transpose 
Q) . reversal (monadic 0). rotate (dyadic , compression (/), pick (dyadic o) and 
disclose (monadic o) . 

The result of the selection expression must be a subset or re-or rongement (or both) 
of selected element locations. Only those selected locations receive the new value 
The value being assigned must have the same shape as the selection expression after 
skipping all dimensions of length 1 in both. 

Examples: 

^<-5 5p 1 2 3 

iik',H)/,N)fO a REPLACE ALL WITH 0 

N 

12 0 3 1 

2 0 3 1 2 

0 3 12 0 

3 12 0 3 

1 2 0 3 1 



(1 10W)'^55 fl REPLACE DIAGONAL 

H 

55 2 0 3 1 

2 55 3 I 2 

0 3 55 2 0 

3 1 2 55 3 

1 2 0 3 55 



Input /Output 



This subsection describes how the user con enter input and display output. 



Input/Output Devices 



The CP-6 APL system gives the user a choice of five input/output methods: 

o APL/ASCII terminal input/output: a terminal with either bit paired or typewriter 
paired APL/ASCII character transmission codes. 

o ASCII terminal input/output. 

o Batch input/output. 

o File Input/output. 

o Blind input/output. 

The input/output described in this section refers to terminals with the APL character 
set. 
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After logging on to CP-6 and invoking APL, the user is in immediate execution mode 
and can enter input whenever the carriage or cursor is indented six spaces. The 
fundamental item of input to APL is the line. A line is a collection of characters 
that does not include the carriage return. Striking the RETURN key completes a line, 
and APL attempts to interpret it and perhaps output data. An incomplete line can be 
corrected as described in Section 2. User input and computer output are easily 
distinguished at the terminal; computer output usually begins at the left margin 
while user input is usually indented six spaces from the left margin. An input line 
Is limited to 390 characters in length, not counting the carriage return (overstrikes 
count OS single characters). 



Types of Input 

CP-6 APL acknowledges four kinds of input: direct, evaluated, quote quad, and blind. 
Direct input occurs when APL is not executing the user's program, evaluated input 
results from quad-input execution, quote-quad input results from quote-quod 
execution, and blind input results from quad-0 through quad-9 execution. Direct 
Input, evaluated input, and quote-quad input are described below and are considered 
to exist only after input translation and current-line editing. Blind Input Is 
covered In Section 16. 



Direct Input 

Direct input is entered during execution mode. APL is ready to accept direct input 
when it skips to a new line and indents six spaces. Evaluation of direct input 
occurs immediately, and the response is either printed at the left margin (If the 
Input was a non— ass i gnment statement) or assigned to a variable (If the Input was an 
assignment statement). Examples of direct Input follow: 

0.625 
10 

l>S<-3 kptl2 
12 3 4 
5 6 7 8 
9 10 11 12 



Evaluated Input 

The quad symbol □ can be used as an argument In a statement, to denote that Input Is 
desired. When APL encounters the quad during statement execution It halts execution 
and requests Input by printing the symbols Q: at the left margin. A response of any 
valid APL expression causes execution to continue, using the value obtained In 
response to the quad symbol. Examples: 



8*D 
2 

k 

□ : 

12 3 4 
5 10 15 20 
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If the quad symbol is built into on input loop, the user can terminate the input 
requested by entering the symbol (not followed by an argument). Simply entering 
nothing and pressing the RETURN key is not sufficient to terminate the input request; 
it will merely cause the □: to reappear at the left margin. An example of escaping 
from an input request is shown below: 

7CUBEiA 
ID LOOP:A*-U 
[2] A*-A*A*A 
[3] A 
Ik] *LOOP 

CUBE 
3 

27 
□ : 

5 

125 



Entering any of the following system commands will terminate an input request: 
)CLEAR, )LOAD, )OFF, )END , )SIC, or )CONTINUE. Entering other system commands merely 
causes the Q: to reappear after the command is executed. 

Functions can be defined during evaluated input. This is similar to function 
definition during normal (direct) input except that at the conclusion of the 
definition, APL re— requests evaluated input. This is to be expected since when APL 
originally requested evaluated input it needed a value, and defining a function 
provides no value. This enhancement is not limited to just providing definition 
capability. The full range of function definition mode features are available during 
evaluated input: 

o Creating a new function 

o Revising an existing non-pendent function (If a function makes an evaluated input 
request, the function becomes pendent. Therefore, that function cannot be opened 
during the evaluated input request): inserting a line, deleting a tine, 
replacing a line, and editing characters of a line. 

o Displaying one or more lines of the open function. 

Entering an )SI or )SINL command in response to an input request will cause the state 
indicator to contain a □. For example: 

10*D 

)SI 

□ 

2 

5 
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Quote-Quad Input 



The quote-quad symbol Q (except when to the left of on assignment arrow) denotes 
literal input. When APL encounters this symbol during statement execution, it awaits 
user input (nothing is printed to prompt for input). Literal character strings are 
entered without beginning and ending quote symbols, and a quote within a string is 
represented by one quote. Quote-quad input always produces a vector result. To 
terminate o request for literal input without having any value associated with the 
variable being requested, press the BREAK key twice. 

Note that if the request for literal input is initiated from within an executing 
function and a double break is entered, execution of the defined function is 
suspended at that point. Examples of quote-quad input are: 

pA 

0 

QUOTES AREN'T NEEDED 
B 

QUOTES AREN*T NEEDED 

X<-' CALIFORNIA**^ 
ABCDEFGHIJKLHN 
X 

111110 0 111 



Output 

As previously mentioned, the display of most computer output begins at the left 
margin. Important output characteristics ore described below. 

1. Width of line. The user can change the number of characters displayed on a line 
to any number from 32 to 390 via the )WIDTH system command (see Section 8), or 
the DPI/ system variable (see Section 11). Output processing always assumes that 
the left and right margin stops are placed full left and full right. 

2. Fractional number. A fractional number is displayed with one leading zero to the 
left of the decimal point, even if the number was entered without zero. Examples 
of fractional numbers are: 

.2+.* 

0.6 

2-^3 

0.6666666667 
.123 

0.123 

3. Exponential notation. APL usually uses exponential form for printing numbers 
less than ir~5, or greater than lEN where N is the value of the UPP system 
variable. Decimal form is used for other coses. Numbers printed in exponential 
form have o magnitude between one and ten followed by an appropriate exponent. 

When on array is displayed, some numbers may be printed in exponential form and 
some in decimal form, depending on the size of each number. Numbers in o vector 
are printed with one space between each number, as shown below: 

1234567.89 123<i567890 1.23456789^10 

When a matrix is displayed, each column of numbers is printed all in exponential 
form or all in decimal form. One number requiring exponential form in a column 
will cause all the numbers in that column to be printed in exponential form. One 
column of blanks separates columns of numbers. Numbers in a matrix are printed 
with decimal points aligned, as shown below: 
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A 

0.0100003 1.23«5ri2 ~1. 99032 
12.3*56703 3.0000r0 7.76767676 

A*ll 

1.000330050£"'22 1 .0U850*23f 133 "19*1.565195 
I. 015*56727^12 1.771*70000^5 6211587288 

4. Significant digits. CP-6 APL carries out all calculations to approximately 18 
significant digits, and displays the result rounded off to the value of UPP 
digits. Any trailing zeros are suppressed in the display. Examples are shown 
below: 

*-^3 
1.333333333 
5*2 

2.5 

The user can use the )DIGITS system command (see Section 8) or the DPP system 
variable to change the number of significant digits displayed, to a number 
ranging from 1 to 20. Examples are shown below: 

*-^3 

1.333 

5*2 

2.5 

5. Comparison Tolerance. The arithmetic functions (addition, subtraction, 
multiplication, and division) are implemented in the computer as functions which 
represent reel numbers through a set of discrete numbers. In CP-6 APL, 
calculations are carried out to approximately 18 decimal digits. Comparison 
tolerance is provided by APL to partly disguise the fact that only 18 digits of 
precision are availoble. The default value of comparison tolerance in a clear 
workspace is ir~13 which causes the equals function to return 1 If the numbers 
being compared are equal in the first 13 digits. An example of comparison 
tolerance in comparison is: 

l=l+"2f~13 "9f"l* 0 9E~lk 2E~13 

0 1110 

6. Numeric and character vectors. Numeric vectors ore displayed with one blank 
between Items, while character vectors ore displayed with no blanks between 
items, as shown: 

2+t6 
3 * 5 6 7 8 

*ABCXYZ' 

ABCXYZ 

If an array contains both numeric and character scalar values, a trailing blank 
column is included ofter each numeric column (except the last column). 

1 'A' 2 

1 A2 



7. Arrays of two or more dimensions. The components of a two-dimensional array 
(i.e., a matrix) are displayed in a rectangular arrangement. The components of 
an array of more than two dimensions (i.e., a higher-order array) are displayed 
as a set of rectangles. Character arrays of two or more dimensions are displayed 
with no spaces between columns. In addition, arrays of more than two dimensions 
ore displayed with extra blank lines separating planes. Examples are shown 
be I ow : 
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3 5p~2+il5 


"1 


0 


12 3 




5 


6 7 8 


g 


10 


11 12 13 






2 3 kDk*-i2k 

w ~ §i/ ^ ■ "fc^ 


5 


6 


7 8 


g 


10 


11 12 


13 


14 


15 16 


17 


18 


ig 20 


21 


22 


23 24 


25 


26 


27 28 



3 kp*HOWISTHETIHE' 

NOWI 
STHE 
TIME 

2 2 5p'ABCDEF GHIJKL MNOPQR* 

ABODE 
F GHl 



JKL M 
NOPQR 

8. Simple. An APL array is simple if every item of the array is either a scalar 
character or a scalar number. 

9. Nested Arrays. An array is nested if it is not simple. That is, an array is 
nested if an item of the array contains another APL array of rank greater than 0. 
Nested arrays, like other APL arrays, are displayed with columns aligned. The 
column width is determined by the widest formatted representation of the items in 
the column. 

The space required to display non-simple items is controlled by the system 
variable UPS. The column width for a non-simple item may be stated as the width 
of the formatted value plus the value (i~HDP5). The row depth for a non-simple 
item can be stated as the number of rows required to display the value plus the 
value (ll*~2tDPS). 

The first two items in UPS control the placement of the arrays within the column 
and row. The first item controls the vertlcol placement of the formatted array 
and the second item controls the columnar placement of the formatted array. The 
first item of UPS con be "1 (top), 0 (center), or 1 (bottom). The second item of 
• UPS con be ~1 (left), 0 (center), or 1 (right). 

The last two items of UPS can be negative to indicate that a vertical bar or box 
be drawn around the border of the array. The magnitude of the value must be 
greater than 1 for the box to be drown. 

The following is an example of displaying nested arrays: 

UPS^O 0 "3 "3 0 CEHTER AND DRAW BOXES 
A^Z 2pt4 0 5<-3 kp'ABCDEFGHIJKL^ 
C*2 3pA B 1 A B 
C 

+ + + + 

11 21 \ABCD\ 7 
13 41 \EFGH\ 

+ + \IJKL\ 

+ -1- 

+ + + + 

Z II 21 \ABCD\ 

13 41 \EFGH\ 

+ + I IJKL I 

+ + 
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UPS^'l 1 0 2 fl DEFAULT VALUE 
C 

1 2 ABCD 7 
3 EFGH 
IJKL 
Z 1 2 ABCD 
3 * £TC// 
IJKL 

10. Prototypes. Every APL array contains a prototype which is the type of the first 
item of the array. For an array whose first item is a simple scalar number, the 
prototype is 0; for an array whose first item is a simple scalar character, the 
prototype is a blank. For all arrays, the prototype has the some structure 
(shape and depth) as the first item and contains zeroes where the corresponding 
item is numeric, and bionics where the corresponding item is character. 

11. Empty arrays. An empty array (an array of no components) can take the form of a 
vector or an array of two or more dimensions. An empty array produces no display 
(just another prompt for input). An empty vector (also known as a null vector) 
can be entered in one of the following ways: lO or or OpO. Similarly, 
examples of entering empty arrays of two or more dimensions ore 0 Zpii and 0 0 
OpO. The display of an empty vector and an empty matrix are shown below: 

to 

0 2p6 
2+2 

Note that an empty numeric vector is represented by the expression lO and any 
empty character vector is represented by the expression These expressions 
cannot always be used interchangeably because their prototypes differ. An 
example is in their use as the right argument in an expansion operation: 

0\»' 

0\iO 

0 

Empty vectors are useful in initializing vectors, in branching, and in the 
limiting coses of some algorithms. 

Note that the use of on empty array as the argument of a scalar function will 
result in an empty array: 

34+pO 
0i<2 0p5 

12. Blind output. Blind output (see in Section 16) is output as one record of 
character (literal) data. 

13. Stopping a display. The user can stop display of output by pressing the BREAK 
key. 

14. Quod output. When □ appears immediately to the left of on assignment arrow, the 
value of the expression to the right of the arrow is output. Example: 

5 

15. Bore output. Normal output includes a concluding carriage return in order that 
the succeeding entry (whether it is input or output) will begin at the first 
position on the following line. Bare output, denoted by expressions of the form 
Ch-JT, does not include a carriage return if the expression is followed either by 
another expression denoting bare output or character input (of the form X*^) . For 
example: 

V F 

111 E*-*TRUE OR FALSE'. THE SQUARE OF • 
12] CH-?* 
[31 B*-* IS • 
141 l!H-(?4)*2 

151 jr*D V 
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F 

TRUE OR FALSE'. THE SQUARE OF 2 IS 9FALSE 
X 

FALSE 



The carriage returns normal iy caused by the width setting iUPW) are still present 
in bare output. 

Because any expression of the form Zh-Jf entered at the keyboard (rather than being 
executed within a defined function) is followed by another keyboard entry, 
(concluded by a carriage return), its effect is indistinguishable from the effect 
of the corresponding normal output. 
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Section 4 

Expression Evaluation 



Order of Evaluation 



The following subsections describe the order in which APL evaluates expressions. 



Right to Left 



APL evaluates expressions from right to left, not from left to right as in most 
written languages. Each function or assignment symbol in an expression operates on 
the entire expression to the right of it. with the rightmost expression evaluated 
first, then the next rightmost, and so on. In illustration, notice the following 
express i on: 

130 

In this expression the result of 5-^-2 is added to 4, and the result of that is 
multiplied by 20, thereby yielding the value 130. 



Precedence of Functions 



Unlike most programming languages (and unlike common algebraic usage) no APL function 
has precedence over another function. A division operation, for example, is not 
performed before an adjacent addition unless, of course, the division appears to the 
right of the addition. Note that in the example cited above, the conventional 
algebraic function hierarchy would have treated the expression as equivalent to 
(20x4) + (5t2), which would hove resulted in the value 82.5. 



Parentiieses 



Parentheses can be used in on expression to depart from the right-to-left rule for 
function execution or left-to— right order for operator execution. They ore used just 
as they are in mathematics for grouping. APL evaluates everything within a poir of 
parentheses (from right to left) before evaluating the expression of which they ore a 
port. There must be on equal number of left and right parentheses. The beginning 
APL user may find parentheses convenient to ovoid confusion over the difference 
between APL and conventional algebraic notation. 

Some examples of the use of parentheses are shown below: 

(3+i5)x2-H 
12 15 18 21 24 

((6*2)x5x4)*3+12 

4 

6*2x5x4*3+12 

2.25 

(20x4)(+)(5*2) 

82.5 
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Precedence of Operators 



Operators have higher precedence than functions. They may be monadic or dyadic (but 
not both); they always produce a function which may be monadic, dyadic or both. The 
left operand of on operator is the expression to the left of the operator up to a 
function (or array) with on array or function to its left. The right operand of a 
dyadic operator is the first function or array to its right. Monadic operators have 
their only argument on their left. 

Unlike functions, operators ore permitted to hove arguments that ore functions. 

Operators and their arguments combine to produce functions (called "derived 

functions") which are then executed like all other APL functions. In fact, the 

derived function that is produced by an operator may be used as an argument to 
another operator. 

A^*o.+/ (0 lOOXO 10 20X1 2 3 *) 
A 

I 2 3 li 
11 12 13 U 
21 22 23 Zii 

101 102 103 104 
111 112 113 lU 
121 122 123 I2k 

In this example, the plus-outer-product reduction is performed on the vector argument 
to produce the scalar enclosed matrix (which is subsequently disclosed by the first 
function). Notice that the + is the argument to the outer product operator o. and 
that this derived function (called plus outer product or is the argument to the 

reduction operator (/) . 



Value of a Variable versus its Name 



When APL encounters a name, it obtains the associated value immediately. This value 
becomes an argument, and the argument will not change value even if the named 
variable is assigned a new value. The following example illustrates this evaluation 
procedure: 

(K<-Z)+K<-1 

3 

The K to the right of the plus sign was evaluated to the argument having, at that 
time, value 1. This argument did not change even through K's value changed before 
the addition was completed. 



Default Output 

Default output occurs when a non-assignment statement is evaluated. That is. the 
result is displayed instead of being stored in memory. For example. 2^4 gives 
default output: 

2x4 

8 

Default output is killed by assignment. For example, the expression A*-2*'i prints no 
output at the terminal. 

A^Z*ii 

Instead, the value 8 is assigned to variable A and stored in computer memory. 

When a compound statement (Section 6) includes both non-assignment and assignment 
expressions, the non-assignment expressions produce output while the assignment 
expressions do not. Some examples are: 
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*+2 0 il*-5+2 ^ 4+3 



Errors and Breaks 



If the user discovers an error in a statement before the RETURN key is pressed, the 
user can RUBOUT to the error and retype the rest of the line as described In Section 
2. (On oil terminals, the standard CP-6 input line editing mechanism is applicable. 
See the CP-6 Programmer Reference Manual (CE40)). An example (using the RUBOUT key) 
i s : 

A-*-5*B*-B*\<R> (<R> Indicates <ESC> R.) 

A 

10 

If the user has entered a line and APL detects an error or double break during 
statement execution, execution of the statement is terminated. If the statement in 
execution contains multiple assignments or is a compound statement, the assignments 
and expressions to the right of the termination point (denoted by a caret) will be 
completed. The current expression and any expressions to the left of the termination 
point will usually not be completed. If a dyadic operator or function is indicated, 
however, its left argument expression (possibly containing assignments) will have 
been completed before the function or operator was invoked. Examples are shown below 
(it is assumed that sidetracking, see Section 10, is not applicable in these 
examples) . 

DOMAIN ERR 

C** + (/)*0)xj^5 

A 

C 

UNDEFIHED 
C 

A 

D 

0 

Z 

5 

il*4*2*.5 0 /'♦O ^ r<-**2+l 0 £*/• 
DOMAIN ERR 

il*4*2*.5 0 F*-0 0 m*2+l 0 E-i-F 

A 

E 

1.333333333 
F 

0 

In both of these examples the user has attempted to divide by zero, thus producing a 
DOMAIN ERR messoge. In the first example the error is detected before variable C is 
assigned a value, so C remains UNDEFINED as shown. In the second example. E and F 
had values assigned to them before the error was detected. 

If the user has entered a line and APL detects a simple error before any part of the 
line is executed. APL displays the message LINESCAN ERR and o caret at the error 
point. The user can type <ESC> D to recall the line in error and edit it to correct 
the problem. For example: 
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At-23ii + ( ) x[>3 
LIHESCAM ERR a 
<D> 

A<-23k + ( )xD*3 

\13<R> 
A*-Z3i^ + (i3)xD*3 

A 

298 362 kZe 

Note that the difference between a LINESCAtf, ERROR and a SilZ) Cffil/! error is that the 
former involves an error in expression logic or syntax, while the latter involves the 
typing of an illegal APL character. 
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Section 5 

APL Primitive Functions 



A primitive function is o symbol indicoting that o basic APL function, such as 
addition or division, is to be performed. A symbol denoting a primitive function is 
either a non-alphanumeric character or a combination of such characters. For 
example, addition is denoted by the + symbol and division is denoted by the -r symbol. 

Some of the basic primitive functions are "monadic" and others are "dyadic". That 
is, some require a single argument and others require two. For example, the 
reciprocal function is monadic (e.g., ■i-A) and the division function is dyadic (e.g., 
A-i-B) . Most of the symbols denoting functions are used for both monadic and dyadic 
functions. APL distinguishes between the monadic and dyadic use of any given 
function by testing for the absence or presence of a left argument. 

o Syntax Conventions 

Syntax conventions used throughout this section are as follows: 



R 


denotes 


the result of a function. 


*■ 


denotes 
left of 


the replacement of any previous value of the symbolic variable to the 
the arrow. 


A 


denotes 


a left argument. 


B 


denotes 


a right argument. 


M 


denotes 


a monadic function. 


D 


denotes 


a dyadic function. 



Following are some examples of the use of these conventions: 

R^H B R^A D B 

o Argument Characteristics 

In discussing functions, certain argument characteristics will be referenced 
frequently. The terms used are described below. 

Domain — In general, the type of data item such as integer data or 
floating-point data. For some functions the domain of on argument 
may be especially restricted (see the example for the circular 
function later in this section). 

Rank - The number of coordinates in an array argument. (A rank of 
zero indicates a scalar.) 

Length — The number of items in a coordinate of an argument. 

Shape - The vector made up of the lengths of al I coordinates of an 
argument . 

o Domain Tables 

In the tables listing the domains of the results for various types of argument 
data, the following symbology is used: 

N denotes numeric data. 

C denotes character data. 
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L denotes logical date (1 or 0). 

I denotes integer data. 

F denotes floating-point data. 

DE denotes a DOMAIN ERR. 

RE denotes a rank error. 



Scalar Functions 



APL functions very considerably in how they reference the items of array arguments 
and in the characteristics (rank and dimensions) of the result compared with those of 
the arguments. A group of functions called scalar functions follow a common set of 
rules with respect to the characteristics of the arguments and results. These 
functions, comprising the arithmetic group, the relotional group, and the logical 
group, are so named becouse they ore defined in terms of scalar arguments. 
Extensions of scalar functions to array arguments ore equivalent to performing 
item-by-item scalar functions. 

If an item of on array contains another APL array, the operation is performed on each 
item within the nested array repeatedly, until the operation selects a simple scalar 
numeric or character item. All of the rank, length and domain checks ore mode at 
each level of nesting. The shape of the resulting structure follows the rules at 
each function application level. 

o Monadic Scalar Functions 

The argument used with a monadic scalar function may hove any rank and 
dimensions. The result has the rank and dimensions of the argument. The domain 
of the result may differ from the domain of the argument. 

o Dyadic Scalar Functions 

If the rank and dimensions of the argument used with a dyadic scalar function are 
the same, the function is performed on corresponding items of the two arguments 
and the result has the some rank and dimensions. If the arguments hove different 
ranks or dimensions and both contain other than one item, a rank or length error 
will be reported. 

If one argument has multiple items and the other is a scalar or single item 
array, the function is performed on the single item with each item of the 
multiple item argument. The result has the rank and dimensions of the multiple 
item argument. If neither argument has multiple items, the result is given the 
shape of the higher ranked argument. The shapes of results of scalar functions 
for various arguments are tabulated below. 
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Right Argument 
S VI Ml HI V M H 



Left 

Argument 



s 


S 


V1 


Ml 


H1 


V 


M 


H 


VI 


VI 


VI 


Ml 


H1 


V 


M 


H 


Ml 


M1 


M1 


M1 


HI 


V 


M 


H 


HI 


HI 


HI 


HI 


HI 


V 


M 


H 


V 


V 


V 


V 


V 


v~ 


RE 


RE 


M 


M 


M 


M 


M 


RE 


M~ 


RE 


H 


H 


H 


H 


H 


RE 


RE 


H^- 



Resul t 



~ Dimensions of arguments must be identical. 

«^Rank and dimensions of arguments must be identical. 

where 



s 


denotes 


a 


scalar. 


V 


denotes 


a 


vector. 


M 


denotes 


a 


mot r i X. 


H 


denotes 


a 


higher order array. 


RE 


denotes 


a 


rank error. 


V1 


denotes 


a 


single item vector. 


M1 


denotes 


0 


si ng 1 e i tern mot r i x. 


HI 


denotes 


a 


single item higher order array 



Arithmetic Functions 



Each function in the arithmetic group has a monadic and dyadic form. If any argument 
is in the character domain, a DOMAIN ERR is reported. Results are always in the 
numeric (integer or floating) domain. If during the execution of any function a 
numeric result exceeds the range of CP-6 APL numbers, a DOMAIN ERR is reported. 
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+ Function (Conjugate, Addition) 



o Monadic -•- is the Conjugate function. 

Domain Table: 

B I C L I F 



R I C L I F 
Examples: 
+5 

5 

+("3 2 l.l) 
~3 2 l.l 

+0 1 0 

0 1 0 

o Dyadic -*- is the Addition function. 
R*-A^B 

Domain Table: 

\B I 

A\ i C L I F 



C DE DE DE DE 
L DE I I F 

1 DE I I/F~ F 
F DE F F F 

~ The result is f loot ing— point if the value exceeds the integer range. 
Examp I es : 

2 3 1+5 "1 0 

7 2 1 

2.5+1 2 3 
3.5 5.5 

2.5 3.5+1 2 3 
LENGTH ERR 

2.5 3.5+1 2 3 



- Function (Negate, Subtraction) 



o Monadic - is the Negate function. 
R*-B 

Domain Table: 

B I C L I F 



R I DE I I/F F 
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Examples: 
-5 

"5 

-("3 2 l.l) 
3 "2 "l.l 

o Dyadic - is the Subtraction function. 
R^A-B 

Domain Table: 



\B 
A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


I 


I 


F 


I 


DE 


I 


I/F~ 


F 


F 


DE 


F 


F 


F 



~ The result is floating-point if the value exceeds the integer range. 
Examples: 

2 3 1-5 "1 0 

"3 k 1 

2.5-1 2 3 
1.5 0.5 "0.5 

1 2 3-2.5 
"1.5 "0.5 0.5 

X Function (Signum, Mu L t i p L i ca t i on ) 

o Monadic x is the Signum function. 
R*-*B 

If B is positive. R is 1. If B is zero, R is 0. If B is negative, R is -1. 
Domain Table: 

B I C L I F 

R I DE L I I 

Examples: 

x~2 3.5 0 .001 
"110 1 

o Dyadic x is the Multiplication function. 
R*A*B 
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Domain Table: 



A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


I 


F 


I 


DE 


I 


I/F~ 


F 


F 


DE 


F 


F 


F 



~ The result is floating-point if the value exceeds the integer range. 
Examples: 

5x1 "I 7 
5 "5 35 

"1 2 0x1.5 2.5 3.5 
"1.5 5 0 

2.5 3x1.7 12 .01 
LENGTH ERR 

2.5 3x1.7 12 0.01 

A 



•f Function (Reciprocal, Division) 

o Monadic ^ is the Reciprocal function. 
R-f-^B 

Domain Table: 

B I C L I F 

R I DE F F F 

If B is zero, the error DOMAIN ERR is reported. 

Examples: 

•^12 5 
1 0.5 0.2 
^-.01 

100 

o Dyadic ^ is the Division function. 
R^A-i-B 

Domain Table: 

\B I 

A\ I C L I F 

C DE DE DE DE 

L DE I/F~ I/F~ F 

I DE I/F*- I/F~ F 

F DE F F F 

~ The quotient is integer if B is an exact multiple of A; otherwise, it is 
f loot ing-point . 
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If B is zero and A is other than zero. 
B and A are zero. R la I. li R exceeds 
DOMAIN ERR is reported. 

Examples: 

7 8 9-^2 10 18 
3.5 0.8 0.5 
0*12 

0 

0-5-0 



the error DOMAIN ERR is reported. If both 
the range of floating-point numbers. 



* Function (Exponential, Exponentiation) 



o Monadic 4r is the Exponential function. 

The monadic * is the equivalent of the dyadic form with e (the base of the 
natural logarithms) supplied as a left argument. The value used for e is 
approximately 2.71828182845904524. 

Rt-*B 

Domain Table: 

B I C L I F 



R I DE F F F 

If B exceeds 352.1187677244522173. DOMAIN ERR is reported. If B is less than 
"355.2379300369719713, R is 0. 

Examples: 

*1 .5 0 "190 
2.718281828 1.648721271 1 3.048234g5ir~83 

o Dyadic * is the Exponentiation function. 

R^A*B 

Domain Table: 



\B 
A\ 


DE 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


I 


F 


I 


DE 


I 


I/F 


F 


F 


DE 


F 


F 


F 



If both A and B are zero. is 1. If il is zero and B is less than zero. DOMAIN 
ERR is reported. If il is less than zero and B is not an integer. DOMAIN ERR is 
reported. If R exceeds range of floating-point numbers, DOMAIN ERR is reported. 

Examp I es : 

0 1 2 '2*0 5.3 0.5 3 
1 1 1.414213562 ~8 

"2*~.3 
DOMAIN ERR 

"2*~0.3 

A 
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® Function (Natural Logarithm, Logarithm) 

o Monadic 9 is the Natural Logarithm (base e) function. 
R*9B 

Domain Table 

B I C L I F 

R I DE F F F 
If £ is not a positive number, DOMAIN ERR is reported. 
Examp I e : 

• 2.7i8281828<(59 1 .0497870683678939(»3 

1 0 "3 

o Dyadic 9 is the Generalized Logarithm (base A) function. 
R*-A9B 

If A or B is not a positive number, DOHAIH ERR is reported. 11 A \a I and B is 
other than 1, DOMAIN ERR is reported. 

Domain Table: 



\B 
A\ 


C 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


F 


F 


F 


I 


DE 


F 


F 


F 


F 


DE 


F 


F 


F 



Examples: 

2 3 1691 27 .25 

0 3 "0.5 

10«10 .1 250 

1 "1 2.397940009 

r Function (Ceiling, Maximum) 

o Monadic T is the Ceiling function. 
R*-JB 

For f , R \a the algebraically smallest integer greater than B-QPT^llB. QCf is 
ir~13 unless it has been reassigned. 

Doma i n Tab I e : 

B I C L I F 

R I DE L I I/F~ 

~ The result Is floating-point if the value exceeds the integer range. 
Examples: 

r 2.1 2.01 ~2.01 2.00000000000000001 
3 3 "2 2 
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o Dyadic r is the Maximum function. 

R is the larger value of A and B. 
Domain Table: 



\B ! 



A\ 


C 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


I 


F 


I 


DE 


I 


I 


F 


F 


DE 


F 


F 


F 



Examples: 
5ri2 

12 

Cl 5 7)r 5 

5 5 7 

"I 2 3.5r"3 "2 7.1 
"I 2 7.1 



L Function (Floor, Minimum) 

o Monadic I is the Floor function. 

IB is the largest integer less than B*\]CT*l\B 
Dome in Table: 

B I C L I F 

R I DE L I I/F~ 

~ The result is floating-point if the value exceeds the integer range. 
Examples: 

L 2.9 2.99 "2.99 2.99999999999999999 
2 2 "3 3 

o Dyadic I is the Minimum function. 
R^AIB 

R is the smaller value of A and B. 
Domain Table: 



\B I 



A\ 


C 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


I 


F 


I 


DE 


I 


I 


F 


F 


DE 


F 


F 


F 
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Examples: 
5112 

5 

51"! 5 7 

~1 5 5 



Function (Absolute Value^ Residue) 



Monadic I is the Absolute Value function. 

Domain Table: 

B I C L I F 



R I DE L I F 
Examp I es : 

rz.is 

2.15 

ri "4.3 5 7.2 
1 4.3 5 7.2 

Dyadic I is the Residue function. 
R*-A\B 

1. If A'O then A\B is B. 

2. If At^O then R lies between A and zero (being permitted to equal zero but not 
A) and is equal to B-N^A for some integer N. 

3. If A'-AIB (using DOT) then iZ is 0. 
Examples: 

A<-2 0 "3 

S<-~6 ~5 "4 "3 "2 "I 0 1 2 3 4 5 6 
Ao.\B 

0120120120120 
"6 "5 "4 ~3 "2 "1 0 1 2 3 4 5 6 
0 "2 "1 0 "2 ~1 0 "2 "1 0 "2 "1 0 

Ji:«-2 1.824 
.OlU 

0.004 

The definition of residue can be stated formally as follows: 

A\B <"* B'A*lBi^A^-A'0 
Domain Table: 
\B ! 



A\ 


C 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


■ DE 


L 


I 


F 


I 


DE 


I 


I 


F 


F 


DE 


F 


F 


F 
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0 Function (Pi Times, Circular) 

o Monadic 0 is the Pi Times function. 
R*OB 

The result is 3.14159265358979324 times B. 
Dome in Table: 

B I C L I F 

R I DE F F F 
Examples: 

01 

3.141592654 
02 .5 

6.283185307 1.570796327 
o Dyadic 0 is the Circular function. 
R^AOB 

The value of A determines the computed function of B according to the following 
convention. 







TabI e 5-1 . Ci rcu 1 or 


Functions 


A 


R 


Domain of 5- 


Range of R~ 


-7 


Archtanh 


U|5 


24.9532985 to "24.9532985 


-6 


Arccosh 


(ls5)A5sW^/*.5— 


3.292722539£'"10 to 0 


-5 


Archs i nh 


iHAX*.5)i\B-- 


+352.811914905 to 0 


-4 


Bx{l-J*"2)*0.5 


UI5 


+352.811914905 to 0 


-3 


Arctan 


MAX^B 


Pi/2 to PI/2 


-2 


Arccos 


l^\B 


0 to Pi 


-1 


Arcsin 


UI5 


-Pi/2 to Pi/2 


0 


(1-5*2)*. 5 


l7t\B 


0 to 1 


1 


Si ne 


4096>|5 


"1 to 1 


2 


Cos i ne 


4096>|5 


"1 to 1 


3 


Tangent 


4G96>|5 


approximately ~6£'18 to 6ri8 


4 


(1+5*2)*. 5 


iMAX*.5)i\B 


1 io MAX*. 5 


5 


Sinh 


352.811914905^15 


-MAX to MAX 


6 


Cosh 


352.811914905215 


1 to MAX 


7 


Tanh 


MAXi\B 


"1 to 1 



~The domains of 5 and ranges of R are narrower than those theoretically possible. 
The limitations reflect the precision with which real numbers are represented and 
with which computations are made in the computer. 



~-/fi4;ir=a.379879956£'152 
Wi»;ir*. 5=2. 89480223 1^76 

For sine, cosine, and tangent functions and their hyperbolic counterparts, 5 is 
expressed in radians. For the inverse trigonometric functions, the value of R is 
in radians. The domain of the result is always floating-point. 

Exomples: 

1002 

"2.064961208r"18 

0O.4 .5 .6 
0.916515139 0.8660254038 0.8 

"70.5 
0.5493061443 
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Notice in the first example that the result (the sine of Z^P'i) should actually be 
zero. The actual result reflects the effect of computing with approximately 18 
decimal-place precision. 



I Function (Factorial, Binomial) 



Monadic ! is the Generalized Factorial function. 

The result is B factorial for non-negative integral value of B. If B is not an 
integer, the result is the gamma function of B^l . 

Domain Table: 

B I C L I F 



R I DE L I/F F 
Examples: 
!7 

5040 

!.66 ".75 0 
0.9016683712 3.625609908 1 

Dyadic ! is the Binomial function. 

R^AIB 

If the arguments are positive integers and A is less than or equal to B, the 
result is the number of combinations of B things taken i( at a time. In general, 
(AlB) is: 

R^r.B)^(lA)^lB-A 

Domain Table: 



\B 
A\ 



I 



C 
L 
I 
F 

Examples: 
1!2 



1.5!2 
1.697652726 

1.5!2.5 

2.5 

5!52 
2598960 



DE DE DE 

DE L I 

DE I 

DE F 



I/F 
F 



DE 
F 
F 
F 
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Relational Functions 



The six relational functions are used to compare two values and return a value of 1 
if the relation is true or a value of 0 if the relation is false. The truth value 
can be used in calculations in the some way as any other value of 1 or 0. The 
relational functions ore strictly dyadic, requiring a left argument. 

The expressions used below to define the relational functions includes a value DELTA. 
This is a relative tolerance value related to the user-established comparison 
tolerance in the following way: 

DELTA*{y:T*(\A)\\B 



< Function (Less Than) 

o Dyadic < is the Less Than function. 
R^A<B 

The result is 1 if (.A-B)<-DELTA, and is 0 otherwise. 
Domain Table: 

\B I . . . _ 



A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


L 


L 


I 


DE 


L 


L 


L 


F 


DE 


L 


L 


L 



Examples: 

2<*.5 

1 

I 2 3<3 2 I 

1 0 0 



^ Function (Less Than or Equal) 

o Dyadic i is the Less Than or Equal function. 
R^A^B 

The result is 1 if (.A-B)^DELTA, and is 0 otherwise. 
Domain Table: 
\B I 



A\ 


C 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


L 


L 


I 


DE 


L 


L 


L 


F 


DE 


L 


L 


L 
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Examples: 

I 

1 2 3^3 2 1 

1 1 0 



Function ( Equa L s ) 



Dyadic = is the Equals function. 

If A and B are numeric, the result is 1 if (.] A-B)iDELTA , and is 0 otherwise. If 
A and B are chorocters, R \s I \f A and B are the same, and 0 if they ore not. 
If one argument is character and the other numeric, R is 0. 

Domain Table: 

\B I 

A\ i C L I F 



C L L L L 
L L L L L 
I L L L L 
F L L L L 
Examples: 

I 2 3=3 2 1 

0 1 0 

'THIS^'^HAT' 
110 0 

•>l'=5 

0 



Function (Greater Than or Equal) 

Dyadic 2 is the Greater Than or Equal function. 
R^-A^ 

The result Is 1 If {A-B)t-DELTA, and is 0 otherwise. 
Domain Table: 



A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


L 


L 


I 


DE 


L 


L 


L 


F 


DE 


L 


L 


L 



Examples: 
U2 

0 

1 2 323 2 1 

0 1 1 
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> Function (Greater Than) 

o Dyadic > is the Greater Than function. 

The result is 1 if iA-B)>DELTA, and is 0 otherwise. 
Domain Table: 



A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


L 


L 


I 


DE 


L 


L 


L 


F 


DE 


L 


L 


L 



Examples: 

2>3.'i 

0 

1 2 3>3 2 1 

0 0 1 



9^ Function (Not Equal) 



Dyadic ^ is the Not Equal function. 

If A and B are numeric, the result is 1 if (\A-B)>DELTA , and is 0 otherwise. If 
A and B are characters. R is 0 tf A and B are the same. 1 if they are not. If 
one argument is character and the other numeric. R is 1. 



Domain Table: 

C L 



\B 
A\ 



C L L L 
L L L L 
I L L L 
F L L L 
Examples: 

1 2 3i<3 2 1 

1 0 1 

*THIS'^*THAT* 
0 0 11 

1 
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Logic£d Functions 



The five logical functions are used to perform logical operations, returning a result 
of 0 or 1. The first four operations ore strictly dyadic, and the last (the "not" 
operator) is strictly monadic. 



A Function (And, LCM) 



o Dyadic ^ is the And function. 

For logical values of ^4 and B (0,1) the result is 1 if >1 and B are both 1, and is 
0 otherwise. Otherwise, the result is the least common multiple of A and B. 

Domain Table: 



\B 
A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


I 


F 


I 


DE 


I 


I/F 


F 


F 


DE 


F 


F 


F 



Examples: 

lAl 

1 

(1<2)A(3=(|) 

0 

1 1 0 OAl 0 1 0 
10 0 0 

3A2 

6 

0.2A0.7 

1.4 



V Function (Or, GCD) 



o Dyadic v is the Or function. 
R<-AvB 

For logical values of A and B (0,1) the result is 1 if either A or B are both 1, 
and is 0 otherwise. Otherwise, the result is the greatest common divisor of A 
and B. 

The greatest common divisor of two values will always be less than or equal (in 
magnitude) to each of the values. The result of this function is always 
non-negative. 
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Domain Table: 
\B I 



A\ 


C 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


I 


F 


I 


DE 


I 


I 


F 


F 


DE 


F 


F 


F 



Examples: 
Ivl 

1 

(l<l)v(3='j) 

0 

1 1 0 Ovl 0 1 0 
1110 

4v6 

2 



A Function (Nand) 

o Dyadic *' is the Nand function. 

The result is 0 if il and B are both 1, and is 1 otherwise. 
Domain Table: 
\B I 



A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


L 


L 


I 


DE 


L 


L 


L 


F 


DE 


L 


L 


L 



A DOMAIN ERR results if both A and B are not equal to either 1 or 0. 
Examples: 
1^1 

0 

(1<2)*(3-*) 

1 

1 1 0 0^1 0 1 0 
0 111 
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V Function (Nor) 

o Dyadic v is the Nor function. 

The result is 0 if either A or B, or both, ore 1, and is 1 otherwise. 
Dofflain Table: 



A\ 


c 


L 


I 


F 


C 


DE 


DE 


DE 


DE 


L 


DE 


L 


L 


L 


I 


DE 


L 


L 


L 


F 


DE 


L 


L 


L 



A DOHAIH ERR results if both A and B are not equal to either 1 or 0. 
Examples: 

0 

(l>2W(3-4) 

I 

1 1 0 Ovl 0 1 0 

0 0 0 1 



~ Function ( Not ) 

o Monadic ~ is the Not function. 
R^B 

The result is 1 if <P is 0, and is 0 if 5 is 1. 
Domain Table: 

B I C L I F 

R I DE L L L 
A DOMAIN ERR results if B is not equal to either 1 or 0. 
Examp I es : 

~1 

0 

-0 

1 

-(2.5-1.5) 

0 
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Mixed Functions 



Functions not cotegorized previously as monadic or dyadic scalar functions ore called 
mixed functions. Rules for shapes and domains of the arguments and results vary and 
are described for the individual functions. 



? Function (RoLL, Deal) 



o Monadic ? is the Roll function. 
R^?B 

Eoch item R[I] of the result is an Integer selected pseudorondomly from (t BlI]). 
The range of the result depends on the value of the index origin (see the deal 
operator below). The shape of the result is the same as that of the right 
argument . 

Examples: 

?5 

3 

?2 li 6 

2 k 1 

?3 3 3 3 
12 3 1 

o Dyadic ? is the Deal function. 
R*A?B 

The result is a vector of integers comprising A components pseudorondomly 
selected from (t B) without replacement, preventing the duplication of integers 
in R. The range of the result depends on the index origin. If the index origin 
is 0, the range is 0 through B-l. If the index origin is 1, the range is 1 
through B. 

A may not exceed B, and both must be simple numeric items. 
Examples: 

4 2 

6?6 
2 13 5 4 6 

A*-10 20 30 40 50 60 70 80 

i<(4?8] 
70 20 10 40 



I Function (Index Generator, Index Of) 

o Monadic t is the Index Generator function. 
Rt-t B 

B must be a single simple numeric item, equal to an integer. The result is a 
simple integer vector comprising B items, beginning with the index origin and 
incrementing monotonical ly by 1. The index origin can be changed by assigning a 
value to D/O. If is 0 the result is on empty numeric vector. 
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Examples: 



I 2 3 k 

0/0«-0 

0 12 3 

o Dyadic i is the Index Of function. 
R^Ai B 

The value of each item of the result is the smallest index / such that All) is 
equivalent to the corresponding item in B. The left argument must be a vector. 
The right argument may hove any rank. If no match for on item of B is found in 
A, that item of the result is set to ipA)*^[2lO. The shape of the result is the 
same as the shape of the right argument. The result is simple and in the integer 
doma in. 

Note that A may be an empty vector and the value of the result depends on whether 
the index origin is 1 (the default case) or 0. A and B may be of any domain. 
Note, however, that if A is all character data, for example, and B is all 
numeric, the result will be entirely "no match" values. 

Examples: 

2 4 6 8t3 

5 

k 

k 2 k 

*xrz* 'DOG*i'o* *xrz' 'x* 'doc 

3 13 2 



c Function (Enclose) 



o Monadic c is the Enclose function. 
R^cB 
R*-<:[K]B 

B may be any APL array. This function increases the depth of 5 by 1 and 
decreases the rank. If an axis is not specified, the result is a scalar whose 
only item is the array J?. If B is a simple scalar character or number, the result 
is B unchanged. 

If on axis is specified, all of the axes specified by K are enclosed, resulting 
in an array of rank {0pB)--fi ,K , containing items of rank p,K, The shape of the 
result is (pS)[ (~(tppS}<X^)/p5] and the shape of each item of B is ipB)lK]. 

Examples: 

UPS^O 0 "3 "3 
c6 

6 

+-+ 
161 
4— <• 

CASEMATE* 
4. 4. 

\SElfATE\ 
+ + 
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ctlJ2 3p* ABCDEF' 

+ — + + — 4- 4- — ••• 

\AD\ \BE\ \CF\ 

+ — + 4- — + + — + 

□PS*"1 1 0 2 

A** STEVE' 'HARK* 'TOM* 'BRUCE* 

Al3]^c'TH0MAS' 

A 

STEVE HARK THOMAS BRUCE 



o Function (Disclose, Pick) 

o Monadic s is the Disclose function. 

R-t-oB 
R*-o[K]B 

The result is on array whose depth is one less than that of B and whose rank has 
increased by the rank of the non— scalar items of B. All of the non-scalar items 
of B must have the same rank although they may vary in shape. If £ is a simple 
array then the result is B. 

If £ is a simple scalar, the result is B. Otherwise if £ is a scalar, the result 
is the array contained in B. 

If axes are specified, they indicate where to insert the axes of the items of B 
into the result. When no axes are specified, the new axes are inserted after the 
axes of B. The number of axes specified must equal the rank of the non— scalar 
items of B. 

Examples: 

0U*-=*WHO* *UHAT* *WHEN* 'WHERE* 

WHO 
WHAT 
WHEH 
WHERE 
k 5 

pD*-:>ll]*STEVE* *HARK* *TOH* *BRUCE* 

SMTB 
TAOR 
ERHU 
VK C 
E E 
5 4 

D'CP-6' 

o Dyadic » is the Pick function. 
R^AoB 

The result is an item from the (p>l)'th level of nesting in B selected by the path 
specified in A. A must be a scalar or vector containing only simple integer 
scalars or vectors. 

The first item of A must contain valid indices of B. These indices select an 
item of B which is then indexed by the next item of A until all items of A have 
been used. The final array is the result of this function. 

If A is empty, the result is B. 
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Examp I es : 

3 oUBCDEFGHIJ' 

C 

2 3 (2 1) 9 1 (1 2 (2 2 pi 2 3 4) 4) 3 2 1 

3 

2 (tO)3 90 91 92 

91 



Function (Depth, Equivalence) 



Monadic £ is the Depth function. 

The result is a simple non-negative integer scalar indicating the maximum depth 
of nesting in P. B may be any APL array. 

The depth of a simple scalar character or number is defined as 0. Non— scalar 
arrays containing only depth 0 items have depth 1. All other arrays have a depth 
of l+r/f"B. 

A depth greater than I indicates that on array is not simple. 
Examples: 
=29 

0 

«23 29 31 

1 

='ABC' k (5 (6 7)) 

3 

CABLE* 'CARS' 

2 

Dyadic = is the Equivalence function. 
R^A=B 

The result is a simple logical scalar indicating whether every item of the left 
argument is equivalent to every item of the right argument. The result is 0 if 
any item of A is not equivalent to the corresponding item of B. 

Comparison tolerance is used if corresponding items of A and B are numeric. 
Arrays are equivalent if they hove the same shape and structure, and if all 
corresponding values in each structure are equal. 

Empty arrays are equivalent only if their prototypes are also equivalent. 
Examples: 

198<iB,1984 

0 

'APPLE'^'PIE' 

0 

10 20^9+1 11 

1 

10 (9 8)^4 (3 2)+6 

1 
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, Function (RaveL, Catenation, Lamination) 



o Monadic , is the Ravel function. 
R^,B 

The result is o vector comprising the components of the argument B in index 
sequence. The argument can have any shape and dimensions. 

Examples: 
B 

1 2 
3 k 

,B 
i 2 2 k 

Bll-.D^cB 
B 

1 2 2 
3 4 
3 k 

,B 

1 2 2 3 <» 
3 k 

[>C*2 kp' LEVELS IX' 

LEVE 
LSIX 

,C 

LEVELS IX 

o Dyadic , is the Catenation and Lamination function. 
R^AAKIB 

The catenation coordinate K is acceptable if (.iK)ft(,ppA)t ppB . The catenation 
coordinate is IK. 

If A and B ore vectors or scalars, the result is a vector comprising all items of 
A followed by all items of B. 

Examples: 

2 3 

B^k 5 6 

A,B 
12 3 4 5 6 

C-t-'STR* 

D<-'AHD' 

C,D,A 
STRAND i 2 3 

Catenat ion 



Arguments A and B are conformable for catenation if: 

1. The ranks ore equal and all coordinates except the catenation coordinate are 
equa I . 

2. The rank of one argument is one less than the other and all coordinates 
except the catenation coordinate of the higher rank argument are equal to ail 
coordinates of the lower rank argument. The lower rank argument is 
subsequently treated as if its rank were equal to the other argument and its 
catenation coordinate length were 1. 

3. Either ^ or B is a scalar. The scalar argument is subsequently treated as if 
its shape were equal to the other argument with a catenation coordinate 
length of 1 . 
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If k and B have conformable shapes and one or both ore of higher rank than 
vector, catenation joins A and B along an existing coordinate. If no coordinate 
is specified, catenation occurs along the lost coordinate. Scalar arguments are 
extended for catenation in this case. 

Exampl es : 

I>W<-* 7p»W' 
MMMMMMM 
MMMMMMM 
MMMHMHH 
HMMHMMM 

1234' 

M,li)X 
MMMMMMM 
MMMMMMM 
MMMMMMM 
MMMMMMM 

xxxxxxx 
xxxxxxx 

w.tnr 

MMMMMMM 
MMMMMMM 
MMMMMMM 
MMMMMMM 
1234567 

M.Z 
MMMMMMM I 
MMMMMMM2 
MMMMMMMZ 
MMMMMMMk 

M.ilW 
MMMMMMM 
MMMMMMM 
MMMMMMM 
MMMHMHH 

0 0 0 0 0 0 0 

H,W 
MMMMMMMo 
MMMMMMMo 
MMMMMMM 0 
HHHHHHHo 

Lam i not ion 



If a non-integer coordinate value is indicated in catenation, and Its celling Is 
a valid coordinate, the function performed Is termed lamination. In this case 
the variable A and B are joined on a new coordinate. The length of the new 
coordinate is always 2. 

In the following examples, the Index origin is 1. If a coordinate of zero or 
less, or three or more, were specified, RANK ERR would be reported. 

Examples: 

«,[.5]l/ 
HHHHHHH 
HHHHHHH 
HHHHHHH 
HHHHHHH 
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0000000 
0000000 
0000000 
0000000 

2 k 7 

ff, [1.511/ 
MMMMMMM 

0000000 

MMMMMMM 

0000000 

MMMMMMM 

0000000 

MMMMMMM 

0000000 

pW, [1.511/ 

2 7 

M,[2.5]W 

MO 
MO 
Mo 
Mo 
MO 
Mo 
MO 

MO 
Mo 
Mo 
Mo 
MO 
Mo 
Mo 

MO 
Mo 
MO 
Mo 
MO 
Mo 
MO 

Mo 
Mo 
MO 
Mo 
MO 
MO 
MO 



li 7 
k 7 2 



PM 

pM,[2.5]W 
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p Function (Shape^ Reshape) 



o Monadic p is the Shape function. 
R^pB 

The result is on integer vector comprising the number of items each index of B 
contains. That is, R contains the highest index in each coordinate of B in 
origin 1. Thus, the expression ppB represents the rank (number of dimensions) of 
B. If f is a scalar, pB results in an empty vector. 

Examples: 

£4-2 4 6 8 
pB 

k 

C*2 Zp' PIFFLE' 
pC 

2 3 

o Dyadic p is the Reshape function. 
R*ApB 

The result is an array with the dimensions specified by vector A end the contents 
of B. Items of A may be positive integers or zero. If any component of A is 
zero, R is empty. If A is empty, R \s a scaler. If B is empty, the prototype of 
B is used to fill the result. If the reshope requires fewer items than B 
contains, only the required items ore in the result. If the result requires more 
items than B contains, B is cyclically reused as required. B may be of any rank 
or domain. 

Examples: 

2p3 4 5 6 

3 k 

2 4pt5 
12 3 4 
5 12 3 



3 3p*AB' 'CDE' *FGHr WKLHN' 
AB CDE FGHI 
JKLHH AB CDE 
FGHI JKLMN AB 



d) Function (Reversal, Rotation) 



o Monadic <D is the Reversal function. 
R*^[K}B 

The result is a reversal along the K'th coordinate of B. If K is omitted, the 
lost coordinate is .ossumed. (If 6 is used instead of <P, the first coordinate is 
assumed) . 

Examples: 

TIME 

0[1]3 3pt9 

7 8 9 
4 5 6 
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I 2 3 

$3 3pi9 

3 2 1 
6 5 4 
9 8 7 

^'FOX' ^WOLVERINE' *DOG* *CAT' 
CAT DOG WOLVERIME FOX 

o Dyadic 0 is the Rotation function. 

R^A^[K]B 

The result is a cyclic rotation of B by the number of components determined by A. 
If A is positive, rotation is to the left; if A is negative, rotation is to the 
right. Rotation is performed along the K'ih coordinate of B. If K is omitted, 
the last coordinate is assumed. (If @ is used instead of ^, the first coordinate 
is assumed). 

Arguments A and B are conformable for rotation if: 

1. ii is a scalar or one element vector. 

2. The rank of A is one less than the rank of B and the shape of A is equal to 
the shape of B omitting axis K. 

A must be a simple integer array. 

Examples: 

3<l)'LEAP' 

PLEA 

203 4pil2 
3 1 2 

7 8 5 6 

II 12 9 10 

"103 'ipil2 
* 1 2 3 

8 5 6 7 
12 9 10 11 

le 3 4pil2 
5 6 7 8 
9 10 11 12 
12 3 4 



Q Function (Transpose) 



o The monadic Transposition function has the following syntax: 
R^B 

The result is an array comprising the items of B with the order of all 
coordinates reversed. For any B, (p^B)=(^pB) . If 5 is a matrix, for example, the 
result is a matrix whose rows are the columns of B and whose columns ore the rows 
of B. Monadic transpose of a scalar or vector yields R*-B. 

Examples: 

CH-il*3 5p • AGENTVIGORAGONY • 

AGENT 
VIGOR 
AGONY 
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AVA 

GIG 
EGO 
NOH 
TRY 

D*-B*Z 3 *p(il2), 100+112 
12 3 4 
5 6 7 8 
9 10 11 12 

101 102 103 104 
105 106 107 108 
109 110 111 112 

4 3 2 



1 


101 


5 


105 


9 


109 


2 


102 


6 


106 


10 


110 


3 


103 


7 


107 


11 


111 


4 


104 


8 


108 


12 


112 



o The dyadic Transposition function has the following syntax: 

The result is an array similar to B except that the coordinates of B are permuted 
according to A. The shape of A and B must be related by 

{pA)-ppB 

There ore two cases of dyadic transposition: 
Case 1 : 

/ is a permutation of ippB (the coordinates of B) . A is described as the inverse 
permutation vector. The AlD'ih component of pR is the /'th component of pB, and 
thus the il[/]'th coordinate of the result is the /'th coordinate of B. 

Examples: 

2 1Q2 3pi6 

1 4 

2 5 

3 6 

3 2 1Q2 2 3p* EXASPERATION* 

ER 
SI 



XA 
PO 



AT 
EH 

Cose 2: 

A satisfies the relationship (tl/A)fAi that is. il is a dense set of the first K 
coordinates of B, permuted, with some coordinates duplicated. If £ is a matrix, 
the one possible form for A is (1 1), and the result is the principal diagonal of 
the matrix. 
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Exomp I e : 



Q*-X^2 3p*GETEARTRY* 

GET 
EAR 
TRY 

1 l^X 

GAY 

If B has rank 3 or more, the rule is that the rank of R equals the highest value 
in A. If 1<WA[I]'A and N<-{A[I]*A)/ipA, then the Allfll]]'ih coordinate of R is 
mode up of those components of B whose H'th coordinate indices are the same. All 
other coordinates of the result ore structured as in Cose 1. 

For higher order arrays, the generalized "diagonal" cose of dyadic transpose is 
varied and somewhat difficult to visualize. The examples below show some forms 
for Case 2: 

Z^Z k lifi* ABCDEFGHIJKLHNOPQRSTUVWX' 
pQ*-Z 

ABCD 
EFGH 
IJKL 
MtfOP 

QRST 
UVWX 
ABCD 
EFGH 
2 k k 

A<-1 I IQZ 
A 

AV 

pA 

2 

B<-1 2 2®Z 
B 

AFKP 

avcu 

P B 

2 4 

C*2 1 l^Z 
C 

AQ 

FV 
KC 
PH 

P C 

4 2 

D^2 1 2Q Z 
D 

AR 

EV 
IB 
MF 

P D 

4 2 

Et-l 2 1(9 Z 
E 

AEIH 
RYBF 

PE 

2 4 

F*-2 2 IQZ 
F 

AU 
BY 
CW 
DX 

PF 

k 2 
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C4-1 2 Z^Z 
G 

AFKP 
QVCH 

PG 

2 <i 

X<-2 3 H 5ptl20 

1 1 1 

1 87 

1 1 1 2^X 
1 2 3 5 

86 87 88 89 90 

2 2 2 IQJT 

1 86 

2 87 

3 88 

4 89 

5 90 

1 \ Z Z^X 
I 7 13 19 

81 87 93 99 

2 2 1 IQJT 

1 81 

7 87 
13 93 
19 99 

I 2 2 3s;i: 
12 3 4 5 
26 27 28 29 30 
51 52 53 54 55 

61 62 63 64 65 
86 87 88 89 90 
111 112 113 114 115 

3 2 2 IGJr 

1 61 

26 86 

51 111 

2 62 

27 87 

52 112 

3 63 

28 88 

53 113 

4 64 

29 89 

54 114 

5 65 

30 90 

55 115 
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^ Function (Grade-up) 



o Monadic i is the Grade-up function. 

The result is a vector of indices (index origin sensitive) of the first 
coordinate of B ranked in ascending order of magnitude. B may be any simple 
non-scalar array containing only numbers or only character items. Identical 
components of B ore ranked in index order. 

If B is Q vector, then the result values ore the indices of the individual items 
of B. If £ is o matrix, the result values are indices of rows of B, and the rows 
ore ranked such that a difference in the first column of B is more significant 
than 0 difference in the remaining columns. This ranking extends to higher 
ranked arrays by sorting on the first coordinate and treating all other 
dimensions in ravel order. 

Ranking Numeric Arrays 



i 5 10 15 20 

1 Z 2 li 

i 3 1 <t 1 

2 4 13 

i5 2p 2819234214 
5 2 3 1 4 

Ranking Character Arrays 



If B is a character array, then kS is treated as AiB where A is the default 
collating sequence shown in Table 5—2. For this default array, difference in 
cose (lower or uppercase) is less significant than a difference in spelling. 
Also, numeric suffixes sort in numeric order. 

Examples: 

A^ll 3p'L10Ll L3 L9 L33L LX LI L20LL L6 * 
6 10 723 11 84195 
AlkA',] 

I 

II 

LX 

L\ 

L3 

L6 

LI 

L9 

LIO 

£30 

L33 
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Table 5-2. 


Default Colloting Sequence Array 


(10 2 27f' M 2 26pUAV165 97o 
ABCDEFGHIJKLMNOPQRSTUVWXYZO 


.+126)), •0123456789M1.5]' ' 


1 




2 




3 




4 




5 




6 




7 




8 




9 





o Dyadic k is the Grade— up function. 



R^AkB 

The result is a vector of indices (Q/O sensitive) of the first coordinate of B 
ranked in ascending order of magnitude using the collating sequence specified by 
the array A. A and B must be simple non— scalar arrays containing only character 
i terns. 

The left argument collating sequence array is arranged such that the indices of 
the first occurrence of each character determines the significance and order for 
the ranking operation. When two characters differ in their indices along the 
columnar axis (the lost dimension), this difference is more significant than a 
difference in indices along the row axis or plane axis. 

For example, to sort an array containing letters and underscored letters, a 
matrix might be used. In this cose, if the first row of the matrix contained the 
letters and the second row contained the underscored letters, the sort would rank 
a difference in spelling (letters) higher than a difference in case. The result 
would cause all similarly spelled words to sort together regardless of their 
case. 

Any characters occurring in B but not in A are treated as though their index 
position in il is beyond the end of each axis of A. 

Examples: 

U*-A^' ABCDEFGHIJKLMHOP • , t . 5 J ' ABCDEFQHIJKLMHOP ' 

ABCDEFGHIJKLMHOP 

U*-B^5 Zp'AHAAMAtL AKAAHU* 

AHA 

AHA 

tL 

AHA 

AM 
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Ai B 

4 12 5 3 

• AEQ.IllEGiELiLKLHKQEABCDEFGHIJKLHllOP • i B 
4 5 3 12 

• AAQBaCQDEEEFaCKHUUKKLLHHKHQOtP ' i B 
4 5 12 3 



^ Function (Grade-Down) 



o Monadic t is the Grade-down function. 
R^fB 

The result is a vector of indices (Q/O sensitive) of the first coordinate of B 
ranlced in descending order of magnitude. B may be any simple non-scalar array 
containing only numbers or only character items. Identical components of B are 
ranked in index order. 

If is a vector, the result values ore the indices of the individual items of B. 
If P is a matrix, the result values are the indices of rows of B and the rows ore 
ranked such thot a difference in the first column of B is more significant than 
the remaining columns. This ranking extends to higher ranked arrays by sorting 
on the first coordinate and treating alt other dimensions in ravel order. 

Examples: 

t 3 I 4 1 5 9 

6 5 3 1 2 4 

t7 2p 31 13273 4 615714 

5 6 4 1 3 7 2 



Ranking Character Arrays 



If B is a character array, is treated as AfB where A Is the default collating 
sequence shown in Table 5-2. For this default array difference in case (letter 
or underscored letters) is less significant than a difference in spelling. Also, 
numeric suffixes sort in numeric order. 

Examples: 

>I^12 Zp'NFDNS NB PEIQUEONTMANSASALBBC HVTYUK' 

12 8 5 4 6 11 2 1 3 7 10 9 

YUK 

SAS 

QUE 

PEl 

OUT 

NWT 

HS 

HFD 

NB 

HAN 

BC 

ALB 

o Dyadic t is the Grade-down function. 
R^AfB 

The result is a vector of the indices of the first coordinate of B orranged such 
that B is ranked in descending order of magnitude using the collating sequence 
specified by the array A. A and B must be simple non-scalar arrays containing 
only character items. 
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The left argument collating sequence is arranged such that the indices of the 
first occurrence of each character determines the significant and order of the 
ranking. When two characters differ in their indices along the columnar axis 
(the last dimension), this difference is more significant than a difference in 
indices along the row axis or plane axis. 

Any characters occurring in B but not in A are treated as though their index 
position in A is beyond the end of each axis of A. 

Examples: 

A2*-2 ZepAO 



B*7 6p': 



UlUllR ZQSOaKTBmmTEK 



6 1 7 3 'I 2 5 

Am 

6 1 7 2 5 3 
AZfB 
'1 6 2 1 5 7 3 



BlAOfB;],' \BlAlfB;],' ' .BlAZfB;] 

Ta^aaa TguMi rmnai 
PtiQiQ. TiK rcsefitf 

ILI[11KB Z&imi Tf^QOll 

um&K iQ&aatL tkk 

TOSOON POSIQ PUQXS. 



1 Function (Base VaLue^ Decode) 



o Dyadic J. is the Base Value function. 
R^AiB 

The argument A is referred to as the radix or radix vector. If is a scalar, it 
is conceptually expanded to a vector. A and B must be simple and numeric; R is 
numeric. 

The argument A is used internally to generate a set of weights. W, to operate on 
B OS follows. Let / be the length of B. Then: 

v[i-i]<-A[i]mn 

WlI-2]lAlI-l]*W[I-l] 
W[1]^A12UV12] 

Note that All] has no effect on the result. 
Example: 

A^O 60 6011 2 3 
W[3] is 1 

W12] is W13]*A[2]. or 60 
U[l] is Wl2nAl2], or 3600 
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The result is formed by W*-.*W: 



1x3600 2x60 3x1 



U*B is 3600 120 3 
R is 3723 

If i4 is a vector and B is on array, qA must be the some as the length of the 
first coordinate of B. If 5 is a matrix for exomple. B must have the same number 
of rows as the length of A. Each column of B is decoded to provide one item of 
the result. If A is also on array, each row of A represents a different radix 
vector. The shape of R is the catenation of the shape of all but the last 
coordinate of A with all but the first coordinate of B. (Structure rules for A, 
B, and R are the same as for inner product.) 

ExampI es: 

211 0 1 1 

11 

413 2 1 0 

228 

lOig 8 7 

987 

1 2 31 45 67 89 

560 

a K IS A TABLE OF TIMES REPRESENTED IN DAYS (ROW 1), 
fl HOURS (ROW 2), MINUTES (ROW 3), AND SECONDS. 

^Kt-ii 6p0 0 0 0 1 11 0 0 0 2 3 13 0 1 16 46 46 46 10.5p40 
0 0 0 0 1 11 
0 0 0 2 3 13 
0 1 16 46 46 46 
10 40 40 40 40 40 

a EACH COLUMN OF K REPRESENTS A TIME VALUE. 

a IF K IS OPERATED ON BY THE *BASE VALUE' FUNCTION, 

0 THE RESULT IS A VECTOR OF TIMES IN SECONDS. 

0 THE RADIX VECTOR IS -- 365 24 60 60 

365 24 60 eOlK 
10 100 1000 10000 100000 1000000 



T Function (Representation, Encode) 



o Dyadic t is the Encode function. 
R*-ATB 

R 19 a "base A" representation of B. R satisfies the relationship 
((*/A)\B-Ai.R)'0 . A and B must be simple and numeric. R is numeric. Note that 
the T and i functions are inverses (opposites). Note also that since Encode 
carries out a residue operation, its values are subject to the rules for that 
function. 

If vector A contains too few items for B to be represented, the most significant 
digits of the result are truncated. If All] is 0, any unencodeabie portion of B 
will be returned as Rli] rather than being truncated.. Note that A and B may be 
negative or non-integer values. In this case, the result is as well defined but 
not as Intuitively clear as for positive integer values. 

B may be an array rather than a scalar, and the shape of the result will be the 
catenation of the shapes of the arguments. (The structure rules for A, A, and B 
are the same as for outer product.) 
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Examples: 

fl BINARY REPRESENTATION 

(8p2)T75 
0 10 0 10 11 



a OCTAL REPRESENTATION 
(3p8)T75 

113 

0 DECIMAL REPRESENTATION 

{5plO)T3Ul5 
3 1 <^ 1 5 

fl VARIED UNIT REPRESENTATION 
Zk 60 60T75<»32 
20 57 12 

a EXAMPLE OF TRUNCATION 
10 10T3U15 

1 5 

0 THE ARGUMENTS FOR REPRESENTATION NEED NOT BE INTEGER 
(8pl.5)T32.75 
1 0.5 1 0 0 0.5 0 1.25 

a H IS A VECTOR OF TIME VALUES IN SECONDS 
H<-10 100 1000 10000 100000 1000000 

fl H CAN BE ENCODED IN TERMS OF DAYS .HOURS .MINUTES AND SECONDS. 

365 Zk 60 60Tif 
0 0 0 0 1 11 
0 0 0 2 3 13 
0 1 16 <(6 46 ke 
10 kO 40 kO kO 40 



ft IN THE RESULT, EACH COLUMN REPRESENTS ONE ELEMENT OF H 
a ROW 1 IS DAYS. ROW 2 IS HOURS. ROW 3 IS MINUTES AND 
fl ROW 4 IS SECONDS. 

The encode function t is based on the residue function in the manner specified by 
the following function for vector A and scalar Bi 

V Z^A ENCODE B 
1 1 ] Z^-O^A 
[21 I^pA 
[31 L:*(/=0)/0 

[4] zin^AiniB 
[5] -►{ii[;]=o)/o 

[6 J B*-{B-Z[I])-i-A[n 
[7] /<-/-l 
[8] *L 
V 
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o Monadic v {s the Format function. 

The symbol « (t and » overstruck) defines two format functions which convert 
numerical arrays to character arrays. The monadic function produces a character 
array which is identical to the array which would be produced if the argument 
were merely printed; the difference (and advantage) is that the result is made 
explicitly available. The monadic format function con also be applied to a 
character array and will return the same character array. When applied to 
numeric arrays, however, the shape of the result is the same as the shape of the 
argument except for the required expansion along the lost coordinate, each number 
being expanded, in general, to several characters. When applied to a nested 
array, the result is a vector or o matrix.. 

Examples: 

PTABLE-^Z'?k *p2 
PTABLE 
1 
0 
0 
1 

pPTABLE 

pU*-DFORHAT^vPTABLE 
1 
0 
0 
I 

9* LITERAL* 
LITERAL 

o Dyadic * is the Format function. 
R-*-A « B 

The dyadic format function accepts only simple numeric arrays for its right 
argument, and uses the left argument to provide detailed control over the result. 
In general, a pair (or pairs) of numbers in the left argument controls one or 
more columns of the result. The first number of the pair determines the total 
width of a number field and the second number specifies the desired precision. 
For decimal form numbers, precision is defined as the number of digits to the 
right of the decimal point; for scaled form it is defined as the number of digits 
in the multiplier. The form to be used is defined by the sign of the precision 
number in the control pair. Negative numbers indicate scaled form. For example: 

pU*-DMATRIX^:i ZplZ.Zk "34.567 0 12 '.26 ~123.*5 
12.3* "34.567 
0 12 
"0.26 "123.45 
3 2 

p012 Z^DMATRIX 
12.340 "34.567 
0.000 12.000 
"0.260 "123.450 

3 24 

pD*-SCALED*-9 'Z^DHATRIX 

\.ZE\ "s.sri 

O.OJTO i.ZEl 
~Z.tE~\ "l.2f2 
3 18 

A single control number moy also be used, and is treated as a number pair with a 
width indicator of zero. In this event, a field width is chosen such that at 
least one space will appear between adjacent numbers. For example: 
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12.34 "3^.57 
0.00 12.00 
"0.26 "123. *5 
3 \h 

\.ZE\ "3.5ri 

O.OJTO 1.2£'l 

"2.6r"l ~1.2f2 
3 20 



Each column of on array con be individually formatted by defining a left argument 
containing a control pair for each column of the array. For example: 

pOO 2 0 2^DHATRIX 
12.3* "3^1.57 
0.00 12.00 
"0.26 "123. *5 
3 14 



p06 2 12 ~3vDMATRIX 
12.34 ~2A6El 
0.00 1.20£1 
"0.26 "1.23f2 
3 18 



When applied to an array having a rank greater than two, the format 
specifications apply to each of the planes defined by the last two coordinates. 
For example: 



HATRIX3D^Z=?Z 2 5p2 

MATRIX3D 
10 111 
0 0 110 



0 10 11 
0 0 0 0 0 



4 \^MATRIX3D 
1.0 0.0 1.0 1.0 1.0 
0.0 0.0 1.0 1.0 0.0 



0.0 1.0 0.0 1.0 1.0 
0.0 0.0 0.0 0.0 0.0 



Tabular displays which incorporate row and column headings or other information 
between columns or rows, can be configured using the format function together 
with extended catenation. For example: 

ROWHEADS-t-k 3p • JAHAPRJULOCr 
YEARS-^l%^t5 

rm£"'«-.001x-4£'5+?4 spsrs 



(• \[\]ROVHEADS) A2^9 ^nSARS) AU^ Z^TABLE 
79 80 81 82 83 

JAH "159.97 153.85 269.01 208.60 "88.20 
APR 8.89 "322.64 293.61 297.76 213.28 
JUL 254.56 73.44 255.15 "134.65 305.28 
OCT 52.33 1.25 "6.41 "234.24 "314.15 

A DOMAIN ERR results when the width indicator of the control pair does not 
specify a size large enough to hold the requested form. The width need not. 
however, provide for blanks between adjacent numbers. 
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i Function (First, Take) 



o Monadic f is the First function. 

B may be any APL array. The result is the APL array which is within the first 
item of B. If B is empty, the result is the prototype value of the array B. 

Examples: 

MO 20 30 

10 

H 

^'SASKATOOH' 'MOOSE JAW 
SASKATOON 

SASKATOON' 'MOOSE JAW 

S 

SASKATOON' 'MOOSE JAW 

S 

fOp(l 2) 3 (k 5) 

0 0 

o Dyadic f is the Take function. 
R^-A^B 

A must be an integer scalar or vector, end the length of A must equal the rank of 
B. (If 5 is a scalar it is treated as though it were a 1 item array whose rank is 
the length of A.) Each item of A controls the "take" from a coordinate of B. R 
has the same rank as B. The shape of R is \A. 

If Ain^O, then the / th coordinate of R is the first All] items in the / th 
coordinate of B. If il[/)<0, the last \A[I] items are used. If \AII] indicates 
more items than are present in the coordinate of B, R is padded with prototype 
values of B. 



ExampI es : 









■3»i5 


3 




5 










7*15 


1 


2 


3 


4 5 0 0 








3t(l 2 3) (4 5) 


1 


2 


3 


4 5 0 0 0 








' '^lO^'OLYMPICS 


0 


0 


0 


0 0 0 0 0 1 1 








+S4-2 2 2pi8 


1 


2 






3 


4 






5 


6 






7 


8 












1 2 2*B 


1 


2 


0 




3 


4 


0 
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^ Function (Drop) 



o Dyadic * is the Drop function. 

A must be integer scalar or vector, and the length of A must equal the rank of B. 
(If S is a scalar it is treated as through it were o 1 item array whose rank is 
the length of >l.) Each item of A controls the "drop" from a coordinate of B. R 
has the same rank as B. The shape of R is Ol(pB)-\A. If o dimension in the result 
thus created would be negative it is set to zero. 

If AID^Q, then the /'th coordinate of R is all but the first All] items of the 
/'th coordinate of Bt that is, the first All] items are dropped. If A[I]<0, the 
last \All] items of the /'th coordinate of B ore dropped. 

Examples: 

"3*i5 

1 2 

3*15 

l^ 5 

+5<-2 2 2pi8 

1 2 
3 k 

5 6 
7 8 

1 2 2*5 n NOTE: RESULT IS AN EMPTY ARRAY 

2 2 UB 
1 1 US 

8 



€ Function (Type, Membership) 



o Monadic < is the Type function. 
R^*B 

The result is an array with the same structure (shape and depth) as B with oil 
numbers replaced by zero and ail characters replaced by blanks. 

Examples: 

cl 2 3 4 
0 0 0 0 

• CHARACTER' 
111111111 

el (2 3) (4 (5 6) 7) 
0 0 0 0 0 0 0 

o Dyadic < is the Membership function. 

R^AtB 

If an item of A is contained in B, the corresponding item of R is equal to 1; 
otherwise, it is 0. The result has the some shape as A and is in the logical 
domain. B moy hove any rank. If A and B ore numeric, DCT is used in the 
equal I ty test . 
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Examples: 



A*' ALPHABET' 
B^* ABODE' 

AfB 

1 0 0 0 1 1 1 0 
1 5 10€C 

110 

*TWO' *TElf**'ONE* 'TWO' 'THREE' 'FOUR' 

1 0 

0 NOTE THAT MEMBERSHIP MAY BE USED WITH NUMERIC VERSUS 
a TEXT ARGUMENTS, BUT THE RESULT IS ALWAYS ZERO 









A'C 




0 


0 


0 


0 0 


0 0 0 








C^A 




0 


0 


0 


0 




0 


0 


0 


0 










1 2 


3«'l 2 3' 


0 


0 


0 







i Function (Execute) 

o Monadic fi is the Execute function. 
R*tB 

B must be o simple scalar or vector. The domain of B must be character unless B 
is an empty vector. Ordinarily, the argument £ wi I I be a small character vector. 
If B contains unbalanced quotes, the error OPEN QUOTE is reported. 

Once the argument has met the above requirements, the execute function departs 
from the mold of the other functions. That is, the characters in its argument, 
if any, are treated as if they were an APL statement to execute. 

It is even possible in CP-6 APL to execute system commands. Execute operations 
con be applied so that an application can create its own variable names, or 
compose new formulas and evaluate them. 

The execute function is a powerful tool. It can, however, be costly in execution 
time. The cost stems from the translation process when accepting its argument as 
if freshly input. This translation Is repeated each time the same execute 
operation is performed: a function line, on the other hand, is translated only 
once regardless of the number of times it is invoked. Thus, 'execute' should be 
used sparingly in interactive or recursive processes. 

As stated previously, the execute function permits formula evaluation, or system 
command execution in the midst of any APL statement. As with evaluated input, 
the result of executing an expression is the value resulting from evaluating that 
expression. The following examples illustrate this: 





*'2+2' 








«• • 'AB' ' ' 


AB 






3+«'2+2' 


7 






X^'Z*' 




Y^'Z' 




3+«ji:,j' 



7 



Executing an empty vector yields an empty (numeric) vector result. 
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0\l»tO» 

0 

0 

There ore three important differences between execute in CP-6 APL and execute in 
most other API's. These ore: 

1. System commands may be the object of execute statements in CP-6 APL. 

2. Function editing is possible using the execute functions in CP-6 APL. 

3. Executing on empty or all blank vector results in an empty numeric vector. 

Executing some system commands yields no result. For example: )OFF, )OFF HOLD, 
)CLEAR, and )LOAD yield no display. In CP-6 APL. the "execute" of a system 
command which produces a display is returned as a character vector. This 
character vector is directly usable by the program. 

The argument to the execute function may contain a number of- expressions 
separated by diamonds. The result of such an argument is the result of the last 
expression evaluated. For example: 

k^i'i 0 2 0 3» 

1 
2 
7 

prints the values 1 and 2, returns 3 as the result of execute, which is added to 
4 to print 7. (The diamond separator is described in Section 6 under Compound 
Statements. ) 

The execute function can also be used to access function definition mode, but 
limitations ore imposed. A basic limitation exists since only one "statement" 
(character vector) con be the argument of an execute function. 

The result of executing function definition mode operation is an empty vector 
unless a function display was requested, in which cose the text of the display is 
returned as the result. 

When using the execute function, the argument cannot contain unbalanced quotes 
(the error message OPEN QUOTE is issued in such coses). 

Error handling is unique in the cose of the execute function. After the 
diagnostic message (such as DOMAIN ERR), the path leading to the error is 
displayed until a normal suspension point is reached. The following example 
illustrates error handling during an involved execute function. 

VZ<-r F X 
[IJ il<-'r+» 
(2] B^'X* 
[3] C*-*iA,B' 
Ik] Z^lOO^-tC 

5 F k 

109 

5 F *FOUR' 
DOMAIM ERR 

A 

iA,B 

A 

Z<-l00f4C 

A 
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o S is the Matrix Inverse function. 

This function is used to solve systems of lineor equations and to invert 
matrices. The monadic form is equivalent to the dyadic form with an identity 
matrix as a left argument, and the function con best be explained in terms of the 
dyadic form. The right argument must be matrix with at least as many rows as 
columns: that is, l=ii/pB). The first coordinate of the left and right arguments 
must hove the same length; that is, (Ifpit) = HpS. A vector argument is treated 
as though it were a one-column matrix; and o scalar is treated as though it were 
a one-by-one matrix, in terms of shape requirements. The shape of the result is 
ipR) = ( Upfi) , ( Hp>l} . For inversion, the shape of the result is ipR) = (OpB) . 
R*-ABB produces R such that the expression +/ { ,A-B+ .*R)-k2 is minimized; that is, 
R indicates the I east— squares solution (or solutions) to a system (or systems) of 
I i near equat i ons . 

If S is a non-singular square matrix, then the minimum is (except for 
computational round-off errors) zero, and R is the solution of a set of 
simultaneous equations. If, in addition. A is an identity matrix, R is the 
inverse of B (that is equivalent to i?<-@B). If >l is a vector, R is the solution to 
one system of simultaneous equations. If >( is a matrix, each column of A 
represents the constants for a linear system with coefficient matrix B, and each 
column of R is the corresponding solution. 

If B is non-square, then the minimum of ,A-B^.*R)le2 is not generally zero, and 
R represent a solution in the I east— squares sense. 

If B is singular (has fewer linearly independent rows than columns), then a SING 
MATRIX error is reported. 

If B is non-square and A is on identity matrix, the result is the left inverse of 
A and the function is equivalent to R*^BB. 

Examples: 

A INVERSE OF A SQUARE MATRIX 

Ofl<H3 3p3 1 * 1 5 9 2 6 5 

3 I Ik 

1 5 9 

2 6 5 

Q*-R*^ 

0.3222222222 "0.2111111111 0.1222222222 
"0. U4'»«i<t44*4 "0.07777777778 0.2555555556 
0.04<l<l<(<(<l44<l<» 0.1777777778 "0.1555555556 



fl VERIFY THAT THE INNER PRODUCT OF R AND B IS 
a ESSENTIALLY THE IDENTITY MATRIX. 

R+.*B 

l.OOOOrO "5.'l210£'~19 "8.6736£""19 
"'i.3368f"19 l.0000£0 "3.2526£'"18 
"2.7l05r~20 "B.iaiSfZO l.OOOOfO 

a LEFT INVERSE OF A NONSQUARE MATRIX 

CH-S4-5 3p3 14158274359876 



3 1 4 

1 5 8 

2 7 4 

3 5 9 
8 7 6 



□PP*5 



U*-R*-BB 



0.074106 
"0.10492 
0.061261 



0.082157 "0.072245 "0.015323 
0.011612 0.17084 "0.048546 
0.06862 "0.073814 0.085902 



0. 13129 

0.013386 

0.04531 
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a AGAIN, VERIFY THAT THE IHNER PRODUCT OF R AND B IS 
a VERY CLOSE TO THE IDENTITY MATRIX 

i.oooofo i.oB^sr'iQ "i.iasefiB 

"1.5179£"18 l.OOOOrO "l.*095£"~18 
1.95l6f~18 8.6736f"19 l.OOOOrO 

fl SOLUTION OF A SINGLE LINEAR SYSTEM 
a B IS THE COEFFICIENT MATRIX 

fl A IS THE VECTOR OF CONSTANTS 

D*-B<-3 3p3 I * 1 5 9 2 6 5 

3 1 li 

1 5 9 

2 6 5 

U*-A<-35 89 79 
35 89 79 

2.U44 8.2111 5.0889 

fi VERIFY THAT B+.xfi APPROXIMATELY EQUALS A 
A-B+ . X/? 

5.5511f"l7 l.ll02r~16 8.3267£"~17 

fl SOLUTION OF A SET OF LINEAR SYSTEMS 

0 B IS A COEFFICIENT MATRIX 

0 A IS A MATRIX; EACH COLUMN IS A SET 

ft OF CONSTANTS FOR B. 

ft EACH COLUMN OF R, WHICH IS A MATRIX, IS THE 

a SOLUTION FOR THE CORRESPONDING COLUMN OF A. 

[>>|4-3 2p35 36 89 88 79 75 

35 36 
89 88 
79 75 

R<-ABB 
R 

Z.lkkk 2.1889 
8.2111 7.1222 
5.0889 5.5778 

0 CHECKING... 

A-B^.^R 
5.5511£'"17 2.7756r"17 
1.1102f"16 8.3267£~17 
8.3267fl7 5.551l£"17 



ft LEAST-SQUARES SOLUTION 
OB*6 2pl 1 1 2 1 3 I * I 5 1 6 

1 1 
1 2 
1 3 
1 4 
1 5 
1 6 

il*l2.03 8.78 6.01 3.75 "0.31 "2.79 
A 

12.03 8.78 6.01 3.75 "0.31 "2.79 
R*-AEB 
R 

14.941 "2.9609 

ft THE RESULT GIVES THE INTERCEPT AND SLOPE OF THE INE 
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fl THAT IS THE LEAST-SQUARES BEST FIT TO THE POINTS OF A. 

11.98 9.0196 6.0588 3.0979 0.13705 "2.8238 
A~B^ .^R 

0.049524 "6.23962 "0.048762 0.6521 "0.44705 0.03381 

To find the values of X, Y, and Z in the following linear equations: 

4Jr + 2r - 5Z = 22 

5;r - 4r + 4Z = "7 

ZX * ZY - 20Z = 80 

assign the values of the coefficients to A and the constant vector to B, as in : 
A 

4 2 "5 

5 "4 4 
2 2 "20 

B 

22 "7 80 

and then obtain the solution: 
BBA 

1 "1 4 

Thus in the linear equations provided above, X has the value 1, Y has the value 
"1 and Z has the value "4. 



Operators 

The five operators in CP— 6 APL extend functions to arrays. In the following 
descriptions of these operations, the bracketed value K represents that coordinate of 
the argument array along which the specified operator is to act. If K is 
unspecified, the last coordinate of the array is assumed. The symbols d, f, and g 
represent any dyadic function, including a primitive function, a system function, a 
defined function, or a derived function. 



Reduction d/ Operator 



o Monadic d/ is the Reduction operator. 
R^d/IK]B 

The result is an array having dimensions equal to that of array B except that the 
^T'th component is not present. If / is used instead of /, the first coordinate 
axis is used. 

For a vector argument, the value of the result is that produced by placing the 
function d between each pair of adjacent components of vector B. A minus 
reduction results in on alternating sum and a divide reduction results in an 
alternating product. 

For a scalar or on array comprising a single component along the reduction 
coordinate, the result has the some value as £. For on empty array the result has 
the value of the identity item of function d as shown in the table below or a 
DOMAIN ERR if no identity exists. 
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Table 5-3. Identity Values for Scalar Functions 


d 


Identity Item 


Conmient 




I 




+ 


0 




■r 


1 


Right identity only. 


- 


0 


Right identity only. 


* 


1 


Right identity only. 


1 


0 


Left identity only. 


« 


None 


0 


None 




V 


0 




A 


1 




A, 


None 




V 


None 




f 


1 


Left Identity only. 


i 


8.37S879g56£lS2 


r 


"8.379879956ri52 




> 


0 


Right identity only. 




1 


Right identity only. 


< 


0 


Left identity only. 




1 


Left ident i ty only. 




1 






0 





Domain restrictions for function d apply. If the function argument d is not a 
scalar function, then the result is a possibly nested array. If B has more than 
one item, the domain of the result is the same as indicated in the domain tables 
for the dyadic scalar functions, or a nested arroy for all other functions. 



Examples: 





0+/2 4 6 


8 


20 






~k 


0-/2 4 6 


8 




O!/10 




10 








APPLE* 




1 








APPLE* 




0 







[>>l<-2 *pt8 

1 2 3 

5 6 7 8 

10 26 

6 8 10 12 

WWA 

36 



□PS4.0 0 "3 "3 

p|>,/* Sp'OATf TVO THREEFOUR • 
+ + 4- + + + + + 

\OHE \ \TWO I \ THREE \ \FOUR I 
+ + + + 4- f + f 

,/ 1 (2 3 *) 5 (6 7 8) 
+ f 

II 2 3 4 5 6 7 81 
+ +■ 
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p/2 3 

+ + 

13 31 
+ + 

p|>p/2 3p4 
+ + + + 

+ + + + 

2 

UPS*-~l 1 0 2 
3 4pi2* 

B 



1 


2 


3 4 


5 


6 


7 8 


9 


10 


11 12 


13 




15 16 


17 


18 


19 20 


21 


22 


23 2k 






+/5 


10 


26 


42 


58 


Ik 


90 






+/[2]B 


15 


18 


21 2k 


51 


5^1 


57 60 








78 


222 








300 










C<-3 kpi 






C 


1 1 


1 


0 


1 1 


0 


0 


1 0 


0 


0 








0 0 


0 










1 0 


0 


0 



Compression A/ Operator (Replicate) 
o Monadic A/ is the Compression operator. 

The result includes all items in B that correspond to a 1 in A. Those 
corresponding to a 0 are suppressed. If either argument is scalar, it is applied 
to oil items of the other argument. 

Compression is performed along the X''th coordinate of B. If K is omitted, the 
last coordinate is assumed. (If / is used instead of /, the first coordinate is 
assumed. ) 

A may be a simple logical scalar or vector, and B may be of any rank or domain. 
If A consists of more than one item, its length must be the same as that of the 
coordinate of B being compressed. 

Examples: 

B*-Z 2pik 
1 0/B 

1 

3 
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The compression operator may be used in a test and branch situation. In this 
case, when the left argument has a value 1. a branch is made to the statement 
indicated by the right argument. If the left argument has the value 0, a branch 
is not taken and execution proceeds with the next statement. For example, the 
statement: 

*(2>Z)/END 0 'VO BRANCH' 
NO BRANCH 

falls through to the next statement; whereas 
■*(3>Z)/END 0 * BRANCH' 
causes a branch to the statement labeled END. 
o The Replicate operator. 
R^A/IK]B 

Like compression, the result includes All] copies of each BID. That is, if 
Ain^O then the corresponding item of B is suppressed, if A[I]-Z then the 
corresponding item of B appears twice and so on. 

Replication follows all the rules of compression except that A may be an integer 
scalar or vector of non-negative values. 

Examples: 

B^2 2pi4 

2 3/B 
112 2 2 
3 3 4 4 4 



Scan d\ Operator 

o Monadic d\ Is the Scan operator. 
R^d\lK]B 

The result has the same shape as that of If \ is used instead of \, the first 
coordinate axis is used. 

For a vector argument, the result is a vector of the same length with values as 
fol lows: 

Rll]*-Bll] 
R[2]<-Bl\] d BIZ] 
Rl3]fBli] d B[Z] d B13] 



Thus the last component of the result is equal to d/B. 

For a scalar or a one-component array, the result is the same as B. For an empty 
argument, the result will be empty. 

Domain restrictions for function d apply. If B has more than one item, the 
result domain is that indicated in the domain table for d if d is a scalar 
function; otherwise the result is a nested array. 

Examples: 

+\1 3 5 7 
1 4 9 16 

+\'5 0 7 0 1 
"5 "5 2 2 3 

-\3 9 5 1 
3 "6 "l "2 

x\l 2 3 4 5 
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1 2 6 24 120 

9 5 ~k 

7 10 0 

,\'ABCD' 
A AB ABC ABCD 

«\'AA' 

A 1 

Scan generalizes to higher ranked arguments in the same way reduction does, by 
doing the operation along the K'th coordinate as shown by the example below: 

B'^Z 3 kptZk 
+\5 



1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


U 


16 


18 


20 


22 


24 


26 


28 


30 


32 


34 


36 






+\t215 


1 


2 


3 


4 


6 


8 


10 


12 


15 


18 


21 


24 


13 


U 


15 


16 


30 


32 


34 


36 


51 


54 


57 


60 






+\B 


1 


3 


6 


10 


5 


11 


18 


26 


9 


19 


30 


42 


13 


27 


42 


58 


17 


35 


54 


74 


21 


43 


66 


90 



Expansion A\ Operator 



o Monadic ^\ is the Expansion operator. 
R^A\IK]B 



A must be a vector of 1's and O's and must include the same number of 1's as the 
length of the coordinate to be expanded. B may be of any rank and domain. 
Expansion occurs along the K'th coordinate of B. If K is omitted, the last 
coordinate is assumed. If \ is used instead of \, the first coordinate is 
assumed. Thus, the difference between \ and \ is 

R*-A\B expands along the last coordinate of B. 

R'*-A\B expands along the first coordinate of B. 

Expansion consists of extending the length of the affected coordinate of B by 
insertion of prototype values in positions indicated by zeros in the argument A. 
The process is best described by example. The prototype for a simple numeric 
array is 0. The prototype of a simple character array is ' *. In general, the 
prototype of an array B is (ccsj?). 

10 10 l\i3 
1 0 2 0 3 

1 0 1\(1 2) (3 4 5) 

1 2 0 0 3 4 5 



a THE FOLLOVIHG EXAMPLES SHOW EXPANSION ON EACH OF THE 
a COORDINATES OF A RANK 3 ARRAY. 
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B<-2 2 2pt8 
1 0 l\B 



I 2 

3 k 

0 0 

0 0 

5 6 

7 8 

1 2 
0 0 
3 4 

5 6 

0 0 
7 8 

1 0 2 
3 0 4 

5 0 6 

7 0 8 



AB 
CD 



1 0 l\[Z]B 



1 0 1\B 



A<-Z 2 2p'ABCDEFGH' 
1 0 



EF 
OH 

AB 

CD 
EF 
GH 

A B 

C D 

E F 
G H 



1 0 l\[2]il 



1 0 l\[3]il 



Inner Product f.g Operator 

o Dyadic f.g is the Inner Product operator. 
R^A f.g B 

The result is an array having shape equal to ail except the last dimension of 
array A catenated with all except the first dimension of array B. If the function 
g is a scalar function, the length of the last dimension of A must be the same as 
that of the first dimension of B, or one of those lengths must be 1. The domain 
of the result is indicated by the functions f and g. Functions f and g may be 
any dyadic functions. For example, R*-A^.*B gives the conventional matrix inner 
product. 

For vector arguments, the result is: 
UA g B 
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Examples: 

3 4+.X5 6 

39 

+/3 6 

39 

1 2 3+.X4 5 6 

32 

+/1 Z 5 6 

32 

1 0 1 O+.Al 1 0 0 

I 

1 0 1 Of.v 110 0 

3 

If i4 is a vector and £ is a matrix, the /'th component of the result is: 

i/A g Bl'.n 

Example: 

£4-2 <tp3 2 6 8 5 4 9 4 
B 

3 2 6 8 
5 k 9 k 





il+.x5 


26 20 


<»8 32 




£[:1] 


3 5 






£[;21 


2 






Bl :3] 


6 9 








8 4 






+/>|x3 5 


26 






+/A*2 k 


20 






+/A*6 9 


48 








32 






1 2 3+.!3 3pi9 



42 68 102 

If >4 is a matrix and B a vector, the 7'th component of the result is: 

i/A[Ii] g B 

Examp I e : 

C^l 2 2 k 
B+.xC 

57 56 

£(1:1 
3 2 6 8 

BlZi] 
5 4 9 4 

*/Bl\;]*C 

57 

+/5(2{ JxC 

56 

For matrix arguments, the /;J'th component of the result Is: 
f/A[Ii] g BliJ] 
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Example: 



(2 lip I 8) + .x4 2p I 8 
50 60 
114 140 

Zp' CANDIDATE* 
r<-3 3p* DRAMATIZE' 

0 0 0 
0 0 0 
0 0 1 

X 

CAN 
DID 
ATE 

Y 

DRA 
MAT 
IZE 

0 1 0 
10 0 

0 0 1 

1 0 1 

0 1 1 

1 1 0 

Inner product also applies to higher order arrays. For the example below, the 
arguments are each three dimensional and the result has four dimensions. The 
I:J:K:Lth item of the result is: WAl I ;J; ]r(Bi iK',L] . 



A^Z 2 3ptl2 
A 

1 2 3 
4 5 6 

7 8 9 
10 11 12 

[>S<-3 2 2p 12+1 12 

13 14 
15 16 

17 18 
19 20 

21 22 
23 24 

110 116 
122 128 

263 278 
293 308 



416 440 
464 488 

569 602 
635 668 

4-/il[l:l;]xS[;l;l] 

110 

4-/il[l:l: ]x5[:l:2] 

116 

4-/il[l{2; ]XB[;2..2] 

308 
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Outer Product o.d Operator 



o Dyadic o.d is the Outer Product operator. 
R^A o.d B 

The result is an array having a shape equal to the shape of A catenated with the 
shape of B. The dyodic function d is performed for each item of A with respect to 
all items of B. The domain of the result is determined by the rules for the 
function d. 

For vector arguments, the I;Jth component of the result is: 

All] d BIJ] 

Example: 

1 2 30. XI 2 3k 

2 k 6 8 

3 6 9 12 

1 (2 3)0. XI (2 3) * 
12 3 k 
2 3 4 9 8 12 

•i*5C'o.,»Z)« *DEF* (2 2p* DEFG') 
AD ADEF ADE 
AFG 

BD BDEF BDE 
BFG 

CD CDEF CDE 
CFG 

Outer product is valid for arguments of higher rank. If. for example. A has a 
rank 3 and B has rank 2, the items of the result are defined by: 

RlItJ;KiL;H] A[IiJ;K) d BlLiH] 



Each Operator 



o Monodic d" is the Each operator. 
R*-d"B 

The result is an array with the same shape as B. Each item of the result contains 
the result of applying the monadic function d to the corresponding item of B. d 
may be any monadic function including a monadic primitive function, o monadic 
system function, a monadic defined function, or a monadic derived function. 

Examples: 

p"'CENTURY' 'DECADE' (1972 1974 1976 1979 1980) 

7 6 5 

9" 'HOW* 'POOL' 'ON' 
VON LOOP NO 

t"2 3 
12 12 3 

4"'1+1' 'PW^BO' 'k*3+i2' 
2 80 16 20 

o Dyadic d" is the Each operator. 

R^A d" B 

The result is on array where each item of the result contains the result of 
applying the dyadic function d to the corresponding items of A and B. 
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A RAtfK ERR Is reported If both A and B ore not singletons and their ranks differ 
A LEHGTH ERR Is reported if both A and B are not singletons and the lengths of A 
and B are not the same. If X or £ Is a singleton. It is reshaped to the rank of 
the higher ranked argument before performing the Each operation. 

d may be any dyadic function, including a dyadic primitive function, a dyadic 
system function, or a dyadic defined function. 

Examples: 

1,"10 20 30 kO 
1 10 1 20 1 30 1 40 

2^"'CENTURY' 'DECADE' (1972 I97k 1976 1979 1980) 
NTURYCE CADEDE 1976 1979 1980 1972 1974 
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Section 6 

APL Statements 



As mentioned in Section 2, each completed line of input is classified as either o 
statement or a system command. Statements specify the operations to be performed by 
APL. such as calculations, branching, and assignment of values or expressions. 
System commands (treated in Section 8) are concerned with the mechanical aspects of 
the system, such as logging off and saving, loading, and deleting workspaces. 
Statements con be entered when the system is in either execution mode or function 
definition mode. The user indicates the end of a statement by pressing the RETURN 
key. In execution mode, the computer then executes the operations contained in the 
statement. In definition mode, the computer stores the statements until the function 
is invoked. Blanks may appear anywhere in a statement except embedded within a 
number or a name. In general, an APL statement cannot be continued on another line. 
A character constant, however, may include one or more carriage returns, thus 
a I lowi ng mu 1 1 i-l i ne statements. 

When a character constant is being entered and APL detects a carriage return before 
receiving the closing quote, it automatically types a closing quote at the beginning 
of the next line. The assumption is that the user may simply have forgotten the 
closing quote. If that is not the case, the user may delete the closing quote and 
continue the text constant. 



VECTOR CONTINUED ON SECOND LINE' 
A 

LONG VECTOR, CLOSING QUOTE NOT FORGOTTEN, 
VECTOR CONTINUED ON SECOND LINE 

In this example, note that APL automatically provides the closing quote in the first 
specification of A. In the second specification, the user cancels APL's action and 
continues the character constant on the second line. 

For oil practical purposes there are four kinds of statements in CP-6 APL: comment, 
branch, assignment and non— assignment , and compound. 



Comment Statements 



To enter a comment statement, the user types the symbol a at the beginning of a line 
and follows it with a comment. The o symbol is produced by typing a n symbol (upper 
shift C) and overstriking it with a o symbol (upper shift J). This symbol signals 
APL that the line is a comment and is not to be executed. Any valid APL characters 
may be included in a comment; invalid APL characters produce an error message. If a 
comment extends over several lines, each line must begin with the a symbol. Some 
examples of comments are shown below: 



A^*LONG VECTOR, CLOSING QUOTE FORGOTTEN 



A 

LONG VECTOR, CLOSING QUOTE FORGOTTEN 

A*-LONG VECTOR, CLOSING QUOTE NOT FORGOTTEN, 



a 

0 

0 
0 



ROOM AREA ROUTINE. 



EACH LINE OF A HULT IPLE-LINE 
COMMENT MUST BEGIN WITH A o. 
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A comment statement can be entered as a direct input line (during execution mode) or 
it can be entered as part of a defined function. If a comment statement is entered 
as o direct input line. It is not retained in the workspace. If a comment statement 
is used in a function definition, however, the statement will hove a line number, 
will occupy workspace, and will be displayed like any other function line. Function 
definition mode cannot be closed on a comment line, because the closing V symbol will 
be treated as just another symbol in the comment. An example of a comment in a 
function definition is shown below: 

^A'^-H TRIAREA B 
tn 0 CALCULATES AREA OF TRIANGLE.. 
[21 A<rH*B^Z 
[3] V 

In CP-6 APL, any executable statement may include a comment to its right. Everything 
to the left of a 0 character is considered executable. Everything to the right is 
considered comment. Some examples ore: 

(10] COST<-HOURS^RATE a COST FOR STRAIGHT'TIME LABOR. 
[15] OCOST'f-l .5^H0URS^RATE a COST FOR OVERTIME LABOR. 

When functions are displayed, comment lines are highlighted by indenting them one 
space less to the left of executable lines. 



Branch Statements 



Branch statements ore generally used within defined functions to alter the sequential 
execution of statements. Another form of branch statement, covered later, is the 
branch arrow that is not followed by on expression. A branch arrow by itself can be 
used to terminate execution of a suspended function and the functions that invoked 
it. thus effectively clearing the state indicator to the next suspension (if any). 
This application of the branch arrow is described in Section 7. A branch statement 
has the general form 

•>exp 

where exp stands for on integer value. The value determines the line number of the 
statement to be executed next, as follows: 

1. If the value is a line number within the current function, that line is executed 
next. Thus the statement 

(5] ■►(2»<)x3 

where A has a value of zero, causes a branch to line 3 of the current function. 
(The value 3 is derived as follows: the expression i2>A) returns a value of 1; 
and this value is multiplied by 3.) 

2. If the value is a line number outside the function being executed, then execution 
of that function terminates. For example, the statement 

indicates a branch to line 0, which is outside the function. Since functions 
begin with line I, branching to line 0 is an effective way to exit a function. 

3. If the value is an empty vector, then no branch occurs and the next sequential 
line is executed. If there ore no more lines, execution of the function is 
terminated. An empty vector can be created in any of the following ways: 

0/S 
Ops 
0*S 

where 0 may be the result of a comparison expression, and S represents a line 
number. (If the result of the comparison statement is 1 instead of 0, the next 
line executed is the one indicated by the line number.) Substituting the 
comparison expression A^ti, which produces a value of 0 or 1, and line 2 in the 
above expressions illustrates the simplicity of this type of branching: 
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[51 ^{A'k)/Z 
15] •♦(i«=*)p2 
151 *(il-<i)*2 

In each case if the value of A equals 4 (that is, the comparison expression 
returns a 1). then line 2 is executed next. If A is any other value, then the 
comparison expression returns a 0, yielding an empty vector, and line 6 wi 1 1 be 
executed next if it exists; otherwise execution of the function terminates. 

The expression indicating the line numbers con be a scalar or a vector. In other 
words, the user can specify branching to one line, to one of two lines, or to one of 
any number of lines. Branching to one line is described above. Branching to one of 
two lines can tal<e either of the following forms: 

^{Sl,SZ){\^X OP n 

■^(.a OP r),~jir op y)/si.s2 

where 

51 is the line number to be branched to if the comparison expression yields o 0. 

52 is the line number to be branched to if the comparison expression yields a 1. 

X OP Y is a comparison expression; X and Y are the values to be compared, and OP 
is any of the following functions: <, =, >, v, a, v, a, e, or «. 

Both of these forms cause a. branch to the first line number if the comparison yields 
0, or to the second line number if the comparison yields 1. In illustration, the 
second form is entered in a defined function, and then executed with values for X and 
Y. 





VX F Y 




[11 


■>^ia<Y),' 


''X<Y)/Al.A2 


[2] 


All 'STEP 


Ai' 


(31 


■^0 




Ik] 


AZ'.'STEP 


AZ* 


[51 


+0 




[61 


7 






I F 2 




STEP 


ill 






2 F I 




STEP 


A2 





Clearly the second form can be expanded to include more line numbers. Similarly, a 
branch to one of several statements can also take the form: 

where 

/ is a counter. 

$ is the rotation function. 

V is a vector of line numbers, the first of which must be a positive integer or 
zero. 

In this case the branch function selects statement I^V as the next one to be 
executed. The following illustration shows how this branch function is carried out 
(see I ine number 3) : 

^HUHB I 

[11 ■►(/^4)/2 0 'LOV 0 *0 

[21 ■>(/s6)/3 0 'HIGH* 0 *0 
[31 5 6 

[41 'FOUR' 0 -^O 

[51 'FIVE' 0 *0 

[61 'SIX' 0 *07 
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LOW 

FOUR 

FIVE 

SIX 

HIGH 



HUHB 3 
NUMB 4 
NUMB 5 
NUMB 6 
tfUMB 7 



See Figure 6-1 for a summary of common branch function formats that can be used; APL 
also offers many other forms of branching. 



Branch to line S or to next line: 

■^iX OP Y)/S 
OP Y)pS 
■^iX OP Y)*S 

Branch to line SI or line 52: 

■►(Sl,S2)tl+;i: OP Y] 

*({X OP Y),~X OP Y)/Sl,S2 

Branch to one of several lines: 

■^(iX OP Y),(X OP Y),X OP Y)/Si,SZ,S2 

S2 S3)[/l 



Figure 6-1. Summary of Common Formats for Branching 



Statement Labels 



Instead of referencing a line number in a branch statement, a statement label can be 
assigned to the branch destination. Referencing that label will obtain the current 
line number of the line. To assign a label to a line, precede the first statement 
with a variable name and a colon, as shown: 

[5] EHD-.A^B^Z 

The label END con now be used in a branch statement to transfer execution to this 
statement. For example, the statement 

[3] *(A<l)/EtfD 

will cause a branch to line 5 if it is less than 1 , or a branch to line 4 if ^ is 1 or 
more. 

The value of a label is the line number with which it is associated at the close of 
function definition. If new lines are Inserted via function editing (see Section 7), 
then the values of the labels are automatically respecified at the closing of the 
function definition. The value of a label cannot be respecified by on assignment; 
any attempt to do so will produce a SYNTAX ERR message. 

Like local variables (Section 3). the integer values of labels in one function can be 
accessed in other functions invoked by the function. 
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Use of a statement label in a branch statement is preferable to use of a line number, 
since function editing may change the original line number. If any lines are 
inserted or deleted during function editing, all lines will be renumbered at the 
close of a function definition mode. For example, consider the following statement 
which specifies a branch to line 5. 

[3] -^5 

If two new statements are inserted between lines 3 and 4, the old line 5 is 
renumbered as line 7 at the close of function definition. However, the branch 
statement will still cause a branch to statement 5 instead of line 7 as now desired. 
This problem can be avoided if labels are used instead of statement numbers as branch 
points. (See Changing Suspended Functions in Section 7 for other considerations 
about labels.) 

When labeled tines are displayed within a function, they are highlighted by indenting 
them one space less than usual. 



Assignment and Non-assignment Statements 

An assignment statement assigns the result of an expression or a value to a variable 
name. It has the general form: 

name ^ expression 

where name can be any variable name and expression can be any APL expression. Three 
examples of assignment statements are 

Z'^(5<l)+3x5 

A non— ass i gnment statement is similar to an assignment statement except that it does 
not have the assignment arrow and the variable name to the left of it; however, a 
non-assignment statement can contain embedded assignments. Examples are: 

3 

(5<l)+3x5 

15 
12 
1 

Notice the differences between assignment and non— assignment statements: (1) 
execution of an assignment statement ends on the assignment, and (2) an assignment 
statement produces no display, while a non-assignment statement displays the 
resulting value of the statement. 
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Using diamonds for separation, all of the preceding kinds of statements can be 
combined in "compound" statements. Compound statements hove the following 
character ist ics: 

1. The statements are evaluated in left-to-right order, with each individual 
statement evaluated in the normal APL manner. Example: 

A*2 k 6 ^ pA ^ A.l 

would produce two lines of output, an integer 3 corresponding to the result of 
the second statement, and a vector 2 4 6 1 corresponding to the third. 

2. An assignment statement produces no display. Example: 

5x4^-2 ^ A<-k 

10 
10 

3. A comment statement con have no statement to its right. Alt characters from the 
comment symbol a up to the end of the line are considered to be commentary. 
Exomp I e : 

3r2 a SHOWS f FUNCTION 0 THIS IS STILL A COMMENT. 

3 

4. A branch statement implies no special display. In the no— branch case, statements 
to the right of the branch will be executed; they are ignored if a branch occurs. 
This provides conditional execution capability. Example: 

^VERACITY X 
[11 ■*(Xii\)/2 0 'TRUE' 0 ■♦0 
12] ■»-{Ar?<0)/3 0 'FALSE' 0 -^O 
[31 'NEITHER TRUE NOR FALSE' 
V 

VERACITY *=2+2 

TRUE 

VERACITY 2+2=4 
NEITHER TRUE NOR FALSE 
2+2=4 

2 

VERACITY (2+2 )«4 

TRUE 

5. If the statement is the subject of an execute function or evaluated input 
request, then the result of the function (or input request) is the result of the 
last expression executed. For example: 

A<-i't9 0 +/t5' 
12 3 4 5 
A 

15 
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Section 7 
Defined Functions 



As mentioned in Section 3, defined functions are used in the same way as primitive 
functions. Defined functions must first, be formed by the user instead of being an 
inherent part of the APL language. 



User-Defined Functions 

The following tasks are handled in function definition mode: 

o Creating user-defined functions 
o Displaying user-defined functions 
o Editing user-defined functions 

Once created, most functions can be edited and displayed. Once a locked function is 
created, however, it cannot be edited or displayed (see "Locking Functions" later in 
this section). Locked function lines cannot even be displayed for error diagnosis. 
It is possible, however, to erase a locked function. 

User defined functions can be created or modified by function definition mode or by 
the UFX system function. They can be loaded or copied from a library workspace or 
"packaged" and read or written to a file (see Section 14). 

Function definition mode begins when a function Is opened and continues until a 
function is closed or abandoned. (It is possible to close o different function than 
was originally opened by revising the name of the function.) A function may be 
"opened" during direct input or evaluated input (see Section 3), and it may be opened 
briefly during execution (see the Execute Operator, i, Section 5). A function cannot 
be opened during any other form of input, such as quote-quad input or blind input; 
and a different existing function cannot be opened while still in function definition 
mode. Until a function is closed during function definition mode, APL execution is 
impossible except for system commands (which are executed and do not become part of 
the function being defined). Most system commands leave the currently open function 
intact and return the user to definition mode; however, some system commands cause a 
function definition to be abandoned (see Issuing System Commands later in this 
section). 



Function Definition Mode 



A del symbol, V, followed by a function name specifies a change from execution mode 
to function definition mode. A second 7 symbol ends function definition mode and 
declares a change back to execution mode. No execution of 
function definition, and no errors are reported except for 



errors, and definition errors, 
f unct ion. 



Instead, each statement is 



statements occurs during 
linescan errors, character 
stored as part of the 



Upon entry to definition mode, 
the last )EDITOR command. The 
similar to the editor provided 
available and the capabilities 
heading Screen Editor later in 



the editor is selected depending upon the setting of 
default function editor is a line-oriented editor 
by other APL systems. A screen editor is also 
unique to screen editing ore described under the 
this section. 
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Each defined function has a header and a body. The function header is the opening 
line of a function and declares the name (the identifier used to reference the 
function) and type of a function. The body of o function is the rest of the 
function. After the user enters a function header, APL responds with a statement 
number as f ol lows: 

VCUBE 

[1] 

The line number [1] signifies that the first line of the function program may be 
entered. Each line thereafter is numbered sequentially until the function is 
completed. The statements are stored and are not executed until definition mode is 
exited and the function named has been referenced. 



Syntax of Defined Functions 

A defined function can be ni Iodic, monadic, or dyadic; that is, it can have zero, 
one, or two arguments. In addition, a defined function may return an explicit result 
or no result. Thus, there ore actually six types of defined functions as illustrated 
by the following table of function header syntax possibilities: 



Table 7—1. Function Header Syntax 


Funct i on 


No Expl ici t Resul t 


Expl icit Result 


Ni Iodic funct ion 
Monadic function 
Dyadic function 


Vname 
Vnome y 
name y 


■*■ name 
Vr ♦ name y 
7r * X name y 



where 



name is the user-assigned function name. 

r is a variable to which the result is returned. 

X and y are dummy variable names. 

The syntax of the function header affects the way a function can be referenced in a 
statement; that is, whether the function requires zero, one, or two arguments for 
execution. Defined functions with explicit results may appear in compound 
expressions, much like primitive functions. Defined functions without an explicit 
result must appear alone; they cannot appear in compound expressions except as the 
last function to be executed. Examples of creation and use of each function type are 
shown in Table 7-2. 

Dyadic defined functions are not strictly dyadic. They may be executed monadically, 
in which case the left argument will be undefined at execution time. The 
function may be used to test for the presence of the left argument. (If the function 
is being executed monadically, the name class of the left argument is 0). 

The result name in the function header may optionally be enclosed in braces ii. If it 
is enclosed, then the result of the function execution will not print if it is the 
primary function on the line (the last function executed). 
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Table 7-2. 


Defined Function Examples 




Function Type 


Header Syntax 


ExampI es 


Ni Iodic function 


Vr <- name 






VRESULT*-PI 




with expl ici t 






[11 


RESULT^Ol 




resu 1 t 






[2] 


7 












PI 










3.14159265<l 












VRESULT^TRIANGLE 










[ 1 ] 


AREA<-0 .5*BASE*HEIGHT 










[2] 


DIAGOMAL*-( (HEIGHT*Z)^BASElcZ )*0 


5 








[3] 


RESULT^AREA .DIAGONAL 










[4 ] 


7 












BASE<-5 












HEIGHT*-B 












TRIANGLE 










20 


9.433981132 




Ni Iodic f unct ion 


Vname 






7/»/ 




with no explicit 






[ 1 ] 


Af^Ol 




resul t 






[2] 


X 










[3] 


7 












PI 










3.1 


It 1592654 












VTRIANGLE 










[11 


AREA*-0 . 5*BASE^HEIGHT 










[21 


DIAGONAL<-{{HEIGHTicZ)*BASE1c2)-kO 


5 








[31 


'AREA IS ' ,vAREA 










[41 


'DIAGONAL IS ' ,vDI AGONAL 










[51 


7 
























HEIGHT'^B 












TRIANGLE 










AREA IS 20 










DIAGONAL IS 9.433981132 




Monadic function 


7r *• name y 






VRETURN^EXPAND INPUT 




wi th expl ici t 






[11 


RETURN<-(i2*p INPUT) pi 0)\ INPUT 




resul t 






[21 


7 












EXPAND 'COPY COMMAND' 










C 0 


P r COMMAND 












7RETURN<-DESCENDINGS0RT INPUT 










[11 


RETURN^ I NPUTl^ INPUT 1 










(21 


7 












DESCEND I NGSORT ~5 "3 10 5 6 


8 








10 


8 6 5 "3 "5 




Monadic function 


7name y 






^EXPAND INPUT 




with no explicit 






[11 


X^{{Z*Q INPUT) pi 0)\INPUT 




resul t 






[2] 


X 










[31 


7 












EXPAND 'COPY COMMAND' 










C 0 


P Y COMMAND 












VDESCENDINGSORT INPUT 










[11 


X^INPUTlflNPUT] 










[21 


X 










[3] 


7 












DESCEND I NGSORT '5 "3 10 5 6 


8 








1 


B 6 5 "3 ~5 
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Table 7-2. Defined Function Examples (cont.) 


Function Type 


Header Syntax 


Examples 


Dyadic function 
wi th expl ici t 
resul t 

Dyadic function 
with no expl ici t 
resu 1 t 


Vr ^ X name y 
Vx name y 


^RESULT*-BASE TRIANGLE HEIGHT 
[ 1 ] AREA*-0 . 5 ^BASE>(HEIGHT 
12] DIAG0HAL^iiHEIGHT*Z)*BASElc2)-k0.5 
t 3 ] RESULT-*- ARE A, DIAGONAL 

in] V 

5 TRIANGLE 8 
20 9.433981132 

7BASE TRIANGLE HEIGHT 
1 1 ] AREA^O .5xBASE^HEIGHT 
1 2 ] DIAGONAL*- ( (HEIGHT*2)+BASE*2)*0 . 5 
[3] 'AREA IS \VAREA 
[4] 'DIAGONAL IS \xDI AGONAL 
[5] V 

5 TRIANGLE 8 
AREA IS 20 

DIAGONAL IS 9.433981132 

PLUS Y 
1 1 ] ANS*-X+Y 
[2] ANS 
[3] V 

2 /"LC/S 5 10 15 20 
7 12 17 22 



Variables Local to a Defined Function 



The three types of variables that can be local to a defined function are: 

o Dummies 
o Loco I s 
o Labe I s 

Dummies and locals ore named in the function header, while labels are named in the 
body of the function. 



Dumm i es 



Dummies are used in the header of a defined function to indicate the syntax of a 
function. For example, notice the header of the following simple function (this 
function calculates the area of a triangle): 

'TA^-H TRIAREA B 
1 1 J A*-H*B^2V 

The dummies A, H, end B in the function header indicate that the function named 
TRIAREA returns an explicit result and that the function operates on two arguments 
which must be furnished by the user. For example, suppose the user calls this 
function with the statement 

AREA^IO TRIAREA 5 
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The dununy H in the function is assigned the value 10, and the dummy B is assigned the 
value 5. The result is returned in the dummy A, and is finally assigned to the 
variable AREA in the calling statement. Dummies possess values only within the 
function. That is. the use of A, H , and B as dummies does not affect their use as 
variables outside the function. If variables A, H, and B have values assigned to 
them before the function is called, they will have the same values after the function 
is executed. For example, suppose the variable A (with value 21) existed in the 
workspace before function TRIAREA was called. A display of variable A after the 
execution of TRIAREA demonstrates that A still has the value 21: 

Af-21 

ARE A^ 10 TRIAREA 5 
AREA 

25 

A 

21 



Body of a Function 

After the opening statement, in which the user creates the function header, the 
process of creating a function consists of inputting function statements and, 
finally, closing function definition. The user is prompted with a function line 
number each time the system is ready for further input. The process is ended by 
typing a closing V followed by a RETURN key. 



Loca L S 



Locals are variables that retain their values only within the function in which they 
ore defined. While a function is active, its local variables take precedence over 
any externally defined variables of the same name. A list of a function's local 
variables is added to the end of the function header, with each variable in the list 
preceded by a semicolon. For example, the function header 

VR-*-A CIRCLE B;X:Y;Z 

indicates that the function named CIRCLE has locals X, Y, and Z. The values for these 
variables ore assigned within the function; if these variables ore referenced without 
having a value assigned within the function, on UNDEFINED error will be produced. If 
variables X, Y, and Z have values assigned to them before the function is called, 
they will revert to those values after the function has finished execution. 



Labels 

Function lines may be labeled to allow symbolically controlled branching (if a 
function is edited, line numbers may change). A labeled line has the form 

[n] name: statement 

where n is the line number, name is the label, and statement is the content of the 
I ine. For example: 

[41 ERREXIT: 'ERROR EXIT* 0 ■►0 

In this example, the label ERREXIT has the value 4. If an attempt is made to assign 
a value to ERREXIT during function execution, a syntax error message will be 
reported. If the function is edited and the line number changes to [5], ERREXIT will 
then hove the value 5. 
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Changing Suspended Functions 



At the time a function is suspended, its (current) local variables have been 
determined by APL. and its labels have already been assigned their values. Changing 
the suspended function does not alter these assignments. Resuming execution of o 
suspended function causes the determined items to remain in effect, regardless of how 
the function was altered. 



Directives 

During function definition mode, editing directives ore used to display, modify, and 
add new lines. A directive may take any one of the following forms: 



[1] 
[IQ] 

tl-5Dl 



[Q 2] 
(2-DJ 



tOJ 

[3-9;/x/] 
[ID 61 

ll-20j2/x/5/y/) 



Directs APL to a line - here line 1 



Directs APL to display a line and to stay 
at that line for further editing — here 
line 1. 



Directs APL to display a range of lines, 
here lines 1 through 5. 



Directs APL to display from a line to the 
end of the function - here beginning at line 
2. 



Directs APL to display the entire function. 



Directs APL to display lines containing a 
string — here string "x" in lines 3 through 9. 



Directs APL to edit a line, starting at a 
given column - here line 1 at column 6. 



Directs APL to change oil occurrences of one 
string to another string in the specified 
range of lines — here the second occurrence 
on each line of the string "x" is changed to 
string "y" in lines 1 through 20. 

The separator S may be replaced by the letter 
F (in which case the replacement string will 
follow the search string), the letter P (in 
which case the replacement string will 
precede the search string), or the letter D 
(in which case the replacement string moy not 
be specified and the search string will be 
deleted) . 

If the occurrence number is omitted, only the 
first occurrence is replaced. If the occurrence 
number is 0. then ail occurrences on each line 
are replaced. 



Directs APL to search for the next occurrence of 
the string 'x' starting at the current line number 
through the end of the function. 
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Directs APL to search for the next occurrence of 
the string 'x' starting at the current line to the 
beginning of the function. 

Directs APL to delete a line - here line 2. 

Directs APL to delete a range of lines - here 
I i nes 4 through 9 . 

[A5-8;/x/] 

Directs APL to delete lines from a range which 
contoin a string - here lines 5 through 8 
containing string "x". 

Directs APL to abandon definition mode and ignore 
oil editing changes made. 

ID] 

In screen editing mode, APL wi II scroll down. If 
not in screen editing mode, an error is reported. 

lU] 

In screen editing mode, APL will scroll up. If 
not in screen editing mode, a DEFN ERR is reported. 

A directive always starts with a left bracket and ends with a right bracket. With 
the exception of search or replacement strings, only legal line numbers, a dash, 
quad, delta, semicolon, slash or backslash are permitted within directives. 

A line number is a number in the range 0 through 9999.999 which contains at most 
three digits after the decimal point. Scientific or E notation is not permitted. A 
line number range contains a dash separating the first line number of the range and 
the last line number of the range. At least one of the line numbers in a range 
directive must be specified. If the first number of a range is omitted, it is 
assumed to be 0. If the second number is omitted, it is assumed to be 9999.999. 
Examples of legal line numbers are: 

0 

123 
0.999 

A quad appearing within the directive indicates a display directive and a delta 
appearing immediately following the left bracket indicates a line delete directive. 

Directives must be the leftmost items input during function definition mode. Several 
directives may be used on one line, however, the rightmost directive overrides all 
directives to the left of it. For example, notice the following portion of a 
function definition: 

7FF 
[ 1 ] X^Y 
12] II] Y<-X 
[2] [5] A<-B 
[6] 

The [1] directive on the third line overrides the [2] directive to its left and 
causes the statement on line 1 to be replaced with Y^X; notice that the next prompt 
is [2]. (It should be obvious by now that a function line prompt is a form of 
directive.) Similarly, the [5] directive on the next line overrides the [2] 
directive to its left and causes line 5 to become the expression A*-B. The next line 
prompt is then [6]. 
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Search and Replacement Strings 



Directive strings are delimited by either a slash or backslash. They may contain any 
characters in the CP-6 APL character set, but if they contain the delimiting 
character, it must be doubled. For example: 

Delimited string String 

/2+>»*0.5/ 2+il*0.5 
/B\C//D/ B\C/D 
/NAME/ HAHE 

In the last example, the string NAME would be found in a line containing * X^NAHE^Z* 
or in a line containing * ARU AHES^Z^ . 

When a search string is specified, the final delimiter may be followed by the 
character A^, which is used to indicate that a string match should only be mode if the 
characters before and after the match are not in the permitted set of identifier name 
characters. This option then allows searches for all occurrences of a specified 
identifier name. For example: 

[3] [^-i^;/K/] 

to] R^A FUN BiEXTRAiX 

[1) EXTRA*-' TESTS' 

IZ] X^A*B 

(3) EXTRA<-EXTRA,v,X 

[5] [0-ki/X/N] 

[0] R-^A FUN B;EXTRA;X 

[2] X-^A-kB 

t3] EXTRA*-EXTRA,^,X 
[5) 

In the first example above, every occurrence of the letter X is displayed, but in the 
second example, only those occurrences of the identifier X are displayed. Note that 
if the identifier X appears within quotes, that line is still displayed. 



Displaying User-defined Functions 



A user-defined function con be displayed in any of the following ways: 

o Display all lines of the function. 

o Display one I ine. 

o Display a range of lines. 

o Display the next line. 

0 Display lines containing a string. 

o Display the next line containing a string. 



Displaying All Lines 



To display a function, the user opens the function with a del symbol, names the 
function, and specifies what is to be displayed, all on the some line. The user con 
then either close the function with another del symbol (if no editing is to be done) 
or leave the function open for further editing. 

If the user wants to display all of a function, function TRIAMGLE for example, the 
procedure is as follows: 

^TRIANGLE (DlV 

V BASE TRIANGLE HEIGHT 
[ 1 ] AREA<-0 .5*BASE*HEIGHT 
[ 2 ] DIAGONAL<-i iHEIGHT*2)^-BASE*Z)*0 . 5 
[3] 'AREA IS \VAREA 
Ik] 'DIAGONAL IS ', ^DIAGONAL 

7 
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Displaying One L i ne 



If the user wants to display only one line of a function, soy line 3 of function 
TRIANGLE, the procedure is 

[31 *AREA IS * .^AREA 



Displaying a Range of Lines 



If the user wonts to display from one line to the end of a function, say from line 2 
of a function TRIANGLE, the procedure is 

VTRI ANGLE I2-D17 
( 2 J DIAGONAL<-( iHEIGHT*Z)+BASE-k2)*0 . 5 
[31 'AREA IS ',^AREA 
ik] 'DIAGONAL IS ' ,^ DIAGONAL 

If the user wonts to display a range of lines, for example, lines 1 through 2 of 
function TRIANGLE, the procedure is: 

VTRIANGLEl 1-2D17 
[ 1 ] AREAt-0 . 5*BASE*HEIGHT 
12] D I AGONAL*- ( (HEIGHT*Z ) +SASE*Z ) *0 . 5 

The display of lengthy functions can be stopped at any point by pressing the BREAK 
key. The user can request the display to start at line 10 and then press the BREAK 
key after line 15 has been displayed. If the display command is closed with a del 
symbol, APL is in execution mode after the interruption. If the closing del is 
omitted, APL is in function definition mode after the interruption. 

Notice that the display commands in all of the above examples ore closed with a del 
symbol. This symbol causes control to be returned to execution mode as soon as the 
display is complete. To remain in function definition mode and edit the function 
instead, the user merely omits the closing del in the display command. See how the 
above examples appear without a closing del in each display command. 

^TRIANGLE IQ] 

V BASE TRIANGLE HEIGHT 
[ 1 J AREA-f-O .5*BASExHEIGHT 
1 2 1 D I AGONAL*- (. (HEIGHT*2)^BASE*2)-kO . 5 
[3] 'AREA IS ' ,VAREA 
Ik] 'DIAGONAL IS ', ^DIAGONAL 

7 

151 

VTRIANGLE [30) 
[31 'AREA IS ' ,^AREA 
[31 

VTRIANGLE [Q 2] 
1 2 1 DIAGONAL*- ( (HErGHT*2 ) ^BASEi^2)*0 . 5 
[31 'AREA IS ' ,TAREA 
Ik] 'DIAGONAL IS ', ^DIAGONAL 
[5] 

Notice that after a single-line display. APL reprompts with the some line number; and 
that after a multiple-line display. APL prompts with the next available line number. 
The user con then edit the function as described below or can enter another del 
symbol to close the function. Closing the function definition with a del symbol does 
not alter the content of that line. For example, the following operation does not 
change the value of i ine 3; it will still be 'AREA IS ' .^AREAi 

^TRI ANGLEiZU] 
[3] 'AREA IS ' ,^AREA 
[3] V 
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In order to find and display the line following a particular line, enter linefeed 
after the closing bracket of a simple line number directive. For example, to display 
the line following 1.5, the procedure is: 

Ik] [1.5] 

1 2 ] DIAGONAL^i {HEIGHT-kZ)+BASE*2 )*0 . 5 

The entire function can be displayed one line at a time by entering linefeed after 
eoch line is displayed. In summary remember that 

[Q] displays entire function. 

[2D1 displays a single line (here 2). 

[Q 2] displays from a line (here 2) to end of the function. 

[1-2D] displays a range of lines (here 1 through 2) 



Displaying Lines Containing a String 

In order to display oil lines containing o particular string of characters, the line 
range to search is followed by a semicolon, on optionol count, and either o slash or 
backslash delimited string. If the count is present, the line is displayed only If 
it contains at least count occurrences of the string. When count is not present, 1 
is assumed. For example, to display all lines in the function TRIANGLE containing 
the string BASE, the procedure is: 

^TRIANGLEi 0-9 ; /BASE/ ] 
10] BASE TRIANGLE HEIGHT 
1 1 ] AREA*-0 . 5*BASE*HEIGHT 
12] DI AGONAL^i (.HEIGHT-kZ ) +fl>ISr*2 )*0 . 5 
[101 

If the search string Is for a particular identifier, the closing slash or backslash 
may be followed by the letter which causes APL to display only those lines in which 
the string Is both preceded and followed by characters that are not legal within a 
name. For example, if the search is for all occurrences of the identifier A, then 
the di rect i ve: 

n-ZQi/A/N) 

will not display a line containing AREA (unless it also contains the name A). 



Displaying the Next Occurrence of a String 

In order to search for the next occurrence of a string, (either forward or backward), 
the directive must contain only a search string. If the search string is delimited 
by a slash, the search begins at the next line through the end of the function. If 
the search is delimited by a backslash, the search begins at the previous line 
through to line zero. If the string is found. APL displays that line and issues a 
prompt for that line. If the string is not found. APL then prompts for the line at 
which the search ended (either zero or 1+ the last line number in the function). For 
example, if the search is for the first occurrence of the string D after line 2. the 
procedure is: 

VTRIANGLE[2][/D/] 
[*1 'DIAGONAL IS '.^DIAGONAL 
[U 
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Editing User-defined Functions 



Editing of user-defined functions is oriented to I i ne-ot-o-t ime editing capabilities: 

o De I et i ng a I i ne 
o Insert i ng a li ne 
o Replacing a I ine 
o Modifying a line 

The first three capabilities can be performed as shown in Table 7-3. The last 
capability, modifying a line, permits character editing (that is, deletion, 
insertion, and replacement of characters), adding to a line, and overstriking 
existing characters on a line. All of these capabilities are detailed below. Column 
one of table 7-3 states the action to be performed. Column two gives on example of 
the action within definition mode. Column three gives an example of the same action 
when exiting definition mode. In both examples the functions ore already open. 



Table 7- 


3. Displaying and Editing Defined Functions 


Act i on 


Within Definition Mode 


Exiting Definition Mode 


Di spl ay ent i re 


r 9 1 r n 1 
I c J lU J 


r 9 1 r n 1 n 
I c J lU J V 


f unct ion 


V F 


V F 




li] A 


[1] A 




I c J a 


f 9 1 D 

I c J a 




(3) C 


[3] C 




V 






r h 1 






[1*] [2D] 


[41 [2D1V 


Id I D 


r o 1 s 




12] 




Display 1 ine 






and change 


[2] B 


[21 B 




[3] 




Display function 


r *i 1 rn 9 1 
1 4 J lU ^ J 


r /i 1 rn 9 To 
1 1 J lU <- J * 


beginning with 


[21 B*-X^Y 


[2] B*-X^Y 


^nA/^ i f i iiH 1 i ha 

III vU 1 i ilw 


[3] C 


[31 C 




V 


V 




[«1 




Delete a line 


[^2] 


[A21V 




[31 




Delete c range 


[41 [^1-2] 


[41(A1-21V 


of lines 


[31 




Insert a 1 ine 


[31 [0.51 X 


[31 [0.51 jrv 




[0.61 




Rep 1 ace o 1 i ne 


[<^1 [21 Z 


[41 [21ZV 


[31 




Override a 1 ine 


ik\ [21 


[41 [21 


number 


[21 


[21 V 


Display a range 


[41 [1-2D1 


(41 [1-2D17 


of lines 


[11 A 


[11 it 




[21 B 


[21 B 




[31 




Find occurrences 


{k\ [0-*;/S/l 


[41 [0-4{/S/lV 


of 0 string 


121 B 


[21 B 


[<»] 
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Table 7-3. 


displaying and Editing Defined Functions (cont.) 


Act i on 


Within Definition Mode 


Exiting Definition Mode 


Find occurrences 
of identifier 


[4] 
[2] 
[4] 


[0-ki/B/N] 
B 


(41 
[2] 


lO-ki/B/N]7 
B 


Find next occurrence 
of 0 string 


[4] 
[3] 
[31 


[lll/C/1 

c 


[41 
[31 


[lH/C/17 
C 


Find previous 
occurrence of a 
st r i ng 


[4] 
[21 
[21 


[\B\J 
B 


[41 
[21 


[\5\1V 
B 


Abort changes, restore 
original version of 
f unct i on 






[41 


[•»] 


Change ol 1 occurrences 
of a string in a 
range of 1 i nes 


[41 
[11 
[41 


[l-3i/A/S/AB/] 
AB 


[4] 
[1] 


l\'Z',/A/S/AB/)^ 
AB 


Change function 
header 


[4] 
[11 


[0] FiB 


[41 


[0] F',BV 


Erase current function 






[41 


)ERASE F 


Erase another 
f unct ion 


[4] 
[4] 


)ERASE G 


[41 
[41 


)ERASE G 
7 



A simple three-line function named F has been assumed in the examples in this table 

(see the first display entry in the table for the original content of function F) . 

Note: The example which illustrates changing a function header, adds a local 
variable to the functional header. 



Deleting a Line 



A statement in a defined function can be deleted by using the delete directive. A 
delete directive may specify all of the line numbers to be deleted. For example, to 
delete line 2 of the following function: 

7BASE TRIANGLE HEIGHT 
[11 0 THIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE 
[21 0 BASE AND HEIGHT CANNOT EXCEED 5 AND 15 RESPECTIVELY 
[31 AREA'(-0.5*BASE*HEIGHT 
1 4 1 D I AGONAL^ ( (HEIGHTI^Z ) *2 )*0 . 5 

[51 'AREA IS • ,VAREA 
[6] 'DIAGONAL IS * ,vD I AGONAL 
[7] 7 

First, the user opens the function and issues the delete directive: 

7TRIANGLEIL2] 
APL responds with a prompt for line 3. 

The user can now either close the function with a del symbol or proceed with further 
editing (including deleting the next line). (The user can also press the RETURN key 
if nothing is to be done to the line. APL simply responds with the line number, in 
this case [3]. A linefeed may be used in place of RETURN in which case APL displays 
the next line of the function.) A display of the function at this point illustrates 
that line 2 is deleted: 
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[3] [Q] 

V BASE TRIANGLE HEIGHT 

[1] 0 THIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE 

[3] AREA^0.5*BASExHEIGHT 

[ ] DIAGONAL'*-({HEIGHTle2)*BASE1e2)-kO . 5 

[5) 'AREA IS ' ,VAREA 

[6] 'DIAGONAL IS '.^DIAGONAL 

[7] 

The function can now be closed with a del syrobol. 
(7] 7 

Once definition mode is exited, APL renumbers the line in sequential order, as 
illustrated by another display of the function 

nRIANGLElD)'J 

V BASE TRIANGLE HEIGHT 

[ 1 ] fl THIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE 
[2] AREA*-0.5>(BASE>(HEIGHT 
1 3 ] DIAGONAL'^UHEIGHTlcZ ) +BASE*Z)*0 . 5 
Ik] 'AREA IS ' ,VAREA 
[5] 'DIAGONAL IS ' .^DIAGNOAL 
7 



Insert i ng a Line 

A new line con be inserted in a defined function simply by reopening the function and 
entering the statement as described below. The user reopens the function by typing a 
del and the function name, to which APL responds by printing the line number of the 
next statement to be entered. If the new line is to be inserted at the end of the 
function, the user can now enter the new statement and close the function as shown: 

VTRIANGLE 

16] a THIS FUNCTION IS USED IN ROUTINES I AND 2. 
[7] 7 

If the new line is to be inserted between two existing lines, however, the user must 
specify a line number between those two lines. For example, suppose the user wonts 
to odd 0 comment as the first line of function TRIANGLE insteod of the last line. 
This con be done as follows: 

VTRIANGLE 
(6] to. 5] 

[0.5] 0 THIS FUNCTION IS USED IN ROUTINES I AND 2. 
(0.6] 

Notice the [0.6] prompt in this example. After on insert statement is entered. APL 
odds 1 to the lost place of the number chosen for the insert, and prompts with the 
new number. (The next prompt after [0.6] will be [0.7]; the next, [0.8]; and so on.) 
This allows the user to insert several lines. 

A display of function TRIANGLE Illustrates that line [0.5] has been added 

[0.6] [□]7 

7 BASE TRIANGLE HEIGHT 
[0.5] 0 THIS FUNCTION IS USED IN ROUTINES I AND 2. 
[ 1 ] fl THIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE 
[ 2 ] AREA^O . 5 *BASE*HEIGHT 
[3] DIAGONAL<-(iHEIGHTlc2)+BASE*2)*0.5 
Ik] 'AREA IS ' ,11 AREA 
[5] 'DIAGONAL IS '.^DIAGONAL 

7 

After the function is closed. APL automatically renumbers the lines, as Illustrated 
by the following display: 
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7TRIANGLE[Q]7 
V BASE TRIANGLE HEIGHT 
[11 fl THIS FUNCTION IS USED IN ROUTINES I AND 2. 
12] a THIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE 
13] AREA<-0.5*BASE*HEIGHT 
[ k ] DIAGONAL^((HEIGHT*2)^BASE1c2 )*0 . 5 
[5] 'AREA IS ' ,VAREA 
[6] 'DIAGONAL IS \^DI AGONAL 



Line Numbers 

APL allows the user to type a line number with up to four numbers to the left of the 
decimal point and up to three numbers to the right. As noted above, after each 
insert line is entered, APL adds 1 to the last place of the insert. As illustrated 
in the following portion of a printout, the next prompt after an [.88] insert will be 
[0.89]; the next. [0.9]; the next, [0.91]; and so on: 

[7] [.881 

[0.88] 

[0.89] 

[0.9] 

[0.91] 

The highest integer line number printed by APL is [9999]; thus the highest possible 
line number is [9999.999]. If the user is prompted with [9999.999] and enters a legal 
statement, APL will prompt with the same line number since it cannot go any higher. 



Rep Lac i ng a Line 



A line in a defined function con be replaced simply by reopening the function, 
directing control to the statement that is to be replaced, and entering the desired 
statement. For example, line 1 of function TRIANGLE is to be replaced with another 
statement. The user reopens the function by typing a del and the function name and 
directs control to line 1 by typing that line number in brackets. After the RETURN 
key is pressed, APL responds to this entry by printing the specified line number at 
the left margin, as shown: 

^TRIANGLEll] 

[11 

Any statement the user enters at this point will replace what previously existed at 
that line. Suppose the user now enters the following comment statement: 

[ 1 ] a INPUT MUST BE IN FEET 
12] 

Notice that the next prompt is at line 2. If no more editing is required, the user 
can close the function by entering another del: 

12] 7 

This action has no effect on line 2; it merely closes the function. The following 
display of function TRIANGLE illustrates the change to line 1: 

VTRI ANGLE IDIV 
7 BASE TRIANGLE HEIGHT 
Ilia INPUT MUST BE IN FEET 

[21 fl THIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE 
(31 AREA <-0.5*BASE*HEIGHT 
[ * 1 DIAG0NAL^UHEIGHT*Z)^-BASElc2 )*0 . 5 
[51 'AREA IS ' ,vAREA 
(61 'DIAGONAL IS ' ,xD I AGONAL 
V 
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Issuing MuLtipLe Directives 



APL allows the user to open a function, chonge a line, and close the function all on 
one line. For example: 

VC[1][212.27 

In this case the user opens function G, issues a directive to line 1 (realizes line 2 
was meant), changes the directive to line 2. replaces whatever exists on that line 
with the value 2.2. and then closes the function. This shortcut operation allows the 
user to change a function without having to interact extensively with the computer. 
Another example is shown below: 



[1] 



VCtlDll.llV 
l.l 



V G 
[11 1.11 
(21 2.2 

7 



The first line requests that line 1 of function C be 
that line changed to the value of 1.11. The display 
has indeed been changed from 1.1 to 1.11. It should 
display one line and change it at the same time, but 
function and change something at the some time. 



displayed, and the contents of 
of function G shows that line 1 
be noted that the user can 
cannot display an entire 



Mod 1 f y 1 ng a Line 



As mentioned earlier, modifying a line involves character editing (that is, deletion, 
insertion, and replacement of characters), adding to a line, and overstriking 
existing characters in the line. Modifications to a line can be specified by 
overriding the present line number with the directive: 

[nDc] 

where n is the number of the line to be edited (0 for a function header), and c is 
the column at which to begin editing (the column position is the number of spaces 
from the left margin). APL wi I I normally display the specified line, and position to 
the designated column. The editing column specified may be 0, in which case APL 
displays the line and stops at the end. If the designated line does not fit on a 
single line, no character editing can be done. In this case, APL simply displays the 
line and then reprompts the user with the some line number. The following is an 
example of such a line: 

121 'A 
B' 

If the typing element is still not in the proper position, the user can backspace, 
tab or use <CTL-R> to space forward until the desired position is reached. 

The I i ne-fflod i f y i ng capabilities of CP-6 APL are identical to those described in the 
CP-6 Programmer Reference Manual (CE40). In summary, the user may enter escape 
sequences to successively modify the content of function lines in a manner similar to 
that afforded direct input. 

NOTE: An escape sequence is generated by pressing the <ESC> key once and 

then the appropriate key for the action desired (e.g., <ESC> followed 
by R for an escape-R sequence). The CP— 6 system prints <R> on 
the terminal in response to an <ESC> R sequence. 

For example, suppose the following function had been previously defined by the user. 

V A PLUS B 

(11 'THE SUM OF AMD ',(•5),' IS '.•il+B 

7 
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Now the user wants to change the function to perform a multiplication rather than an 
addition. Suppose the function that will do this is called TIMES. To proceed with 
the example, the user opens the function for editing with 

7PLUS 

and APL responds with [2]. The user types [ID 0] to tell APL to display line 1 and 
remain at the end to await new instructions. 

IZ] [ID 0] 

[IJ 'THE SUM OF ',(»>!),• AND IS '.M+B 

APL waits at the end of the displayed line. The user presses RUBOUT twice to delete 
the B and then the and enters <ESC> followed by R to retype the line. The line 
appears as: 

[1] 'THE SUM OF AND IS \vA^B\\<R> 

The two backslashes indicate the rubouts and <R> indicates the <ESC> R sequence. APL 

immediately types 

[1] 'THE SUM OF •,(•/),' AND '.CB),' IS ' 

and waits after the last A. Now the user types and enters <ESC> V S to move to the 
5 in SUM. 

[11 'THE SUM OF '.(^A),' AND IS ' ,^A*B 

The terminal now waits at the S for more instructions. Now the user presses RUBOUT 
three times to delete S then U then M enters <ESC> J to switch to CP-6 insert mode 
types PRODUCT and then <ESC> R to show the line. 

[1] 'THE SUM OF ',{^A),' AND IS ' ,VA*B 

\\\PRODUCT<R> 

ID 'THE PRODUCT OF 'A^A),' AND '.(^B),' IS ' ,xA*B 

APL now waits for input at the T in PRODUCT. The user has decided to change the name 
of the function to TIMES. First, the user presses RETURN to tell APL that a new line 
1 has been defined. APL responds with [2]. The user rewrites line 0 directly and 
ends function definition all in one line. 

[21 10] A TIMES BV 

Now the user demonstrates the new function. 

U TIMES 6 
THE PRODUCT OF k AND 6 IS 2* 

0 Tl MES 9 
THE PRODUCT OF 0 AND 9 /S 0 



Adding Characters to End of Line 

To odd one or more characters to the end of o line, specify rero os the column at 
which to begin editing. APL will then display the line unaltered and wait at the end 
of the line for the user to add something. An example of adding local variables to a 
function header is shown below: 

[3] [00 0) 

[0] RETURN^FUNC XiAiB 
[11 

In this case APL typed the header as RETURN't-FUNC X and waited at the end of the line, 
and the user typed iAiB. 
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Overstriking a Character 

To edit a line and create a legal overstrike. specify zero as the column at which to 
begin editing. APL will display the line and wait at the end of it; the user can 
then backspace to the character to be overstruck, and type the second character. An 
example of overstriking a character is shown below: 

[8] [5D 0] 
15] A*^ 



In this case the first line caused statement 5. consisting of the expression A*U, to 
be displayed and APL to wait at the end of the line. The user then backspaced to the 
quad and typed on apostrophe, thus creating the legal overstrike Q. 



Editing a Line Number 

Line numbers may be edited in the same way that the content of a line is edited. One 
application of editing line numbers is in repeating a statement at several different 
lines. For example, the following procedure can be used to repeat the contents of 
I i ne 2 at I i ne 4. 1 : 

7C[2D 1] 
[2J A^20^12*A 

APL waits under the [. The user presses <CTRL— R> to move under the 2, presses RUBOUT 
to delete it. enters <ESC> J to switch to insert mode, types 4.1, and enters <ESC> R 
to see the result. 

[2] /l'^30-M2xi» 

14.11 A^30^12*A 

When the user now presses RETURN, a new line 4.1 has been defined. The contents of 

line 2 remain the same; that line was merely copied to line 4.1. 



Changing a Function Header 



There are four changes the user can make to a function header (that is, to line 
zero) . 

1. Change the name of the function. Suppose the user reopens an existing function 
called FFl and changes only the name of the function to Gl as shown below: 

WHO] 
[0] RETUM^-Gl ARG 
[11 

This example assumes that CI does not already exist. (If it did, a DEFH ERR 
message would be reported.) 

Changing the function name has no effect on function FFl, the function still 
exists as it did before the reopen. Of course, FFl is no longer the open 
function, Gl is. CI is initially a copy of FFl and any modifications 
subsequently mode while in function definition mode apply only to CI. This 
feature allows synonymous function names as long as only the header is revised. 
It is possible for a user to make c locked version of on unlocked function in 
this manner, retaining the unlocked version only until satisfied that the locked 
version is error-free. Erasing the original function does not affect o 
synonymous function, nor does subsequent revision of the original. A synonymous 
function retains the stop and trace vectors supplied with the original function 
when it was copied. 

2. Change the name of the result, change a function with a result to a no-result 
function, or change a no— result function to a function with a result. The 
following illustrates the change of function fFl's result name from RETURN to Ri 
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[01 R^FFl ARG 
[11 

3. Change the name of on argument. An example is shown below, where function FFl*a 
argument is changed to X: 

7FFH0] 
[01 R^-FFl X 
[11 

4. Change the names of locals, insert locals, or delete locals. APL does not allow 
the user to delete a function header. Any ottempt to do so will cause APL to 
print on error message and reprompt the user with line zero. To get rid of the 
current function, the user must issue an )ERASE command. 



Screen Editing 

CP-6 APL provides a screen-oriented editor for editing defined functions. The screen 
editor is requested by the )EDITOR system command. In this mode, o portion of the 
function being edited is always on the screen, and the bottom of the screen typically 
contains an area for error messages and the output of system commands. To modify a 
line, position to the character or characters to be changed and enter the appropriate 
characters to be inserted or replaced. To position the cursor to a porticular line, 
enter <ESC> X and one of the line positioning directives listed below. In order to 
leave screen editing mode, enter o V character at the end of a line or enter an <ESC> 
XV sequence. Please note that in this section, the sequence "<ESC>" indicates 
pressing of the escape key on the terminal. 

Whenever the cursor moves off a line. APL determines whether the line is changed or 
if a directive was entered. A directive can be entered at anytime by typing <ESC> X 
followed by the directive. The line that was erased in order to enter the directive 
reappears as soon as the directive is acted upon. Display directives ore not 
permitted in screen editing mode (mainly because the function is already being 
displayed). If the screen does not contain the portion of the function requiring 
modification, the line to be modified can be reached by entering linefeed characters 
to get to it, or by entering a bore line number directive such as [6] (which would 
position the cursor to line 6). 

Table 7—4 contains a list of character sequences to perform some common input 
editing. For a complete list of screen editing input editing sequences, see the CP— 6 
Programmer Reference Manual (CE40) . Table 7-5 contains a list of the directives that 
may be entered in screen editing mode and their meaning. 



Table 7—4. Screen Editing Control Characters 


Input 


Meaning 


<ESC>A 

<ESC>P 

<ESC>N 

<ESC>- 

<ESC>V? 

<ESC>J 

<ESC>K 

<ESC>X 

<ESC>» 

<ESC>: 

<ESC>N<ESCXLF> 

<ESCXBS> 

<ESCXLF> 

<BS> 
<CTL-R> 
<CTL-I> 
<tab> 


Pos i t i on one 1 i ne up . 

Restore line to its contents when the cursor arrived. 
Position to the end of the line. 
Repaint the screen. 

Position the cursor to the next *?• character. 
Toggle insertion mode. 

Delete characters to the end of the line. 

Delete all characters on the line. 

Remember the characters in the insertion window (or 

1 i ne) . 

Copy characters remembered by <ESC>* into line. 

Insert a line after the current line. 

Join current line to previous or next line. 

Split current line by inserting a new line following 

the current 1 ine. 

Position backward one choracter. 

Position forward one character. 

Position forward to next tab setting. 

Position forward to next tob setting. 
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Table 7-5. Screen Editing Directives 


Input 


Meani ng 


[n] 


Position to line n if directive has nothing following 
it. Otherwise replace line n with the remaining 
text. 


[/string/] 


Position to the next higher line number which contains 
the string 'string* . 


[\str ing\] 


Position to the next lower line number which contains 
the string 'string' . 


[An] 


Delete 1 ine number n. 


[An-fn] 


Delete line numbers n through line m. 


[An-in;/st r/] 


Delete line numbers n through line m if they 
contain the string 'str'. 


[-] 


Abandon screen editing mode ignoring all 
editing changes. 


[n-m;c/x/S/y/] 


Replace the c'th occurrence of the string 'x' 
with the string 'y' in lines n through m. 



Issuing System Commands 

CP-6 APL allows the user to enter any system command while in function definition 
mode. Most system commands keep the user in function definition mode, while some 
system commands (described below) return the user to execution mode or even exit APL. 
After commands that keep the user in definition mode. APL will prompt with the same 
line number at which the command was given. For example, suppose the user is at line 
5 of a function and wants to find out the names of variables in the workspace: 

[5] )VARS 
AAA BAT DDD 
[5] 

The system commands that exit function definition mode ore: )CLEAR, )LOAD, )COPY, 
)PCOPY. )QLOAD, )QCOPY. )QPCQPY , )CONTJUUE, )COHTINUE HOLD, )OFF, )OFF HOLD, )END, 
)SAVE, and an )ERASE of the current function. All of these commands force a close of 
the definition mode as though the user had closed it, but the resulting disposition 
of that function depends on the command. The )CLEAR, )LOAD, )QLOAD , )ERASE, )OFF, 
and )EHD commends cause the function to be discarded; the )SAVE, )COPY , )PCOPY, 
)QCOPY. )QPCOPY. )COHTINUE, and )COHTINUE HOLD commands automatically reopen the 
function after the command has finished. In the lost situation, as soon as the 
command has finished, APL signals the user of the reopening by printing the function 
name (with on opening del) and prompting with the next available line number. With 
the )CONTINUE and )COtfTINUE HOLD commands, of course, the function is not opened 
until the next APL session. The user should display the function before doing any 
more editing, since renumbering may hove occurred because of the forced close. 
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Function Execution 



APL permits recursive functions (those which reference themselves when they are 
executed). APL also allows the user to suspend function execution. These topics are 
discussed in detail below. 



Recursive Functions 



Recursive functions reference themselves in the body of their definitions. As on 
example, notice the following function which returns the factorial of its argument: 

VZ*-FAC H 

ID Z^l 0 ■►(ysD/O 0 Z*-N^FAC W-lv 
FAC 0 

1 

FAC 1 

1 

FAC k 

2ii 



Suspending Execution 

Execution of a function is suspended (stopped) before completion, if any of the 
following occurs: the BREAK key is pressed, on error is encountered (unless 
sidetracking occurs, see section 10). or a user-set stop control is reached (see 
USTOP) . When a suspension occurs, APL prints the name of the suspended function and 
the line number at which it was suspended. At this point, APL is in direct execution 
mode (subject to any [^A requirements, see Section 11). Any functions that can be 
performed in execution mode are applicable during function suspension. As long as a 
function is suspended, its local variables are active and can be examined and 
modi f ied. 

The user can resume execution of a suspended function by specifying a branch. 
Entering a branch arrow followed by a RETURN key clears that suspension, while 
specifying a branch to a particular line number resumes execution at the beginning of 
that line (that is, at the right end of that line). Branching to a line outside a 
function's range of line numbers, or zero, terminates the execution of that function. 

As 0 general rule, it is best not to leave a function suspended, because the 
information about that function occupies workspace which is valuable to the APL user 
(see State Indicator). In addition, each time the user attempts to execute an 
already suspended function, even more information about that function is added to 
computer memory. Thus, if the user has no specific reason to leave a function 
suspended, it should be cleared before proceeding with the rest of the program. (See 
also the )SIC command in Section 8.) 



State Indicator 

APL maintains a "state indicator" that gives o list of all suspended and pendent 
functions (that is, all "active" functions). A suspended function is one where 
execution is stopped before completion (see Suspending Execution). A function Is 
pendent unless specifically suspended. Most commonly, this is observed when one 
(pendent) function has called a suspended function. As a rule, suspended functions 
are stopped between lines, while pendent functions are stopped in the middle of a 
line. Note, however, when a function is suspended due to on error, the error marker 
may indicate the middle of the line; nevertheless, the function is stopped between 
that line and its predecessor. A display of pendent and suspended functions can be 
obtained via the )SI system command, with the most recent active function displayed 
first. 
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)SI 
ZIZ] * 

r[3j 

ZIZ] * 
XIZ] 
W15] * 

An asterisk after an entry indicates a suspended function; absence of an asterisk 
indicates a pendent function. The bracketed number after a function name is the 
number of the next line to be executed. If there ore no suspended or pendent 
functions in the state indicator, no report will result from the )SI command. The 
number of items in the state indicator con be determined by typing the expression 

pOlc. 

Unlike suspended functions, pendent functions cannot be erased, copied over, or 
edited. As an example, look at the state indicator list shown above. Functions Z 
and W can be edited but functions X and Y cannot. Notice that function X is listed 
as both pendent and suspended; it cannot be edited because it is pendent in one of 
its states. Also notice that function Z has been suspended twice. 

There is one instance in which a pendent function will not be listed in the state 
indicator. Suppose a dyadic function is about to be executed, pending resolution of 
its left argument. Assume that argument is obtained as the result of some function, 
soy F, and F is suspended. Then the dyadic function is pendent, because it is ready 
to execute as soon as F is resumed. But the dyadic function is not listed in the 
state indicator because it has not yet entered a state of execution. Fortunately, 
this situation is rare andseldom will confuse the user. 

The system command )SINL lists the contents of the state indicator, including a list 
of variables local to pendent and suspended functions. Using the command )s1nL lists 
the fol lowing: 



)SIlfL 



ZIZ] 


* 


A 


B 


Xlii] 


*• 


AA 




YIZ] 








Z[2] 


*• 


A 


B 


X[2] 




AA 




W[5] 


*■ 







As with the )SI command, the most recent active function is displayed first. This 
example indicates that variables A and B are local to function Z and that variable AA 
is local to function X. Only the local variables of the most recent active functions 
can be accessed by the user. Thus, the user can access local variables A and B of 
the lost invocation of function Z, and variable AA of the lost invocation of X. But, 
the user cannot access local variables A and B of the first invocation of function Z 
or local variable AA of the earlier invocation of function X (see XIZ]). 

The user con clear the state indicator by using the branch arrow (that is, . Each 
branch arrow clears one suspended function and its associated pendent functions; 
thus, to clear the entire state indicator, the user enters a branch arrow for each 
asterisk in the list. For example, the user con clear the previous indicator. 





■* 




)SItfL 


X[k] 


* AA 


Y[3] 




ZIZ] 


* A 


XIZ] 


AA 


W15] 


)S[NL 


ZIZ] 


* A 


XIZ] 


AA 


W15] 


)SINL 
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The )SIlfL commands in this example show what is left in the state indicator after 
each branch arrow. The user can also clear the same state indicator by entering four 
successive branch arrows. 

■» 

)SIML 

In this case, the )SINL command shows that nothing is left in the state indicator. 
The easiest way to completely clear the state indicator is to issue a )SIC command. 

CP-6 APL provides limited protection against SI DAMAGE. As an example, suppose the 
user opens function F and modifies the header, changing the function's type (e.g., 
monadic to dyadic, result to no-result) and then attempts to close function F. If F 
is not suspended, the function is closed as usual. If f is suspended, APL issues a 
warning (to the effect that references in the state indicator will be damaged by the 
change to the header) and requests a response from the user. The user can either 
order the close to occur with SI DAMAGE by typing YES followed by a RETURN, or cancel 
the close in order to revise the function further, hopefully correcting the header. 
Only a type change requires this protection. It is perfectly permissible to make 
other changes to the header, such as adding locals or renaming the result or dummy 
arguments; however, this is seldom advisable (see Changing Suspended Functions 
above) . 



Locking Functions 



A function con be locked during definition or editing by using on opening or closing 
9 { V overstruck with ~) instead of a V. A locked function con be executed, copied, 
or erased, but it cannot be displayed, suspended, or altered. After a function is 
locked, any associated trace control or stop control is automatically reset. 
Examples of locking functions ore: 

9 HH VHH 9 HH 

[8] 7 [8] 9 [8] 9 

Once locked, if on error exists that is not sidetracked in the function, the error is 
implicitly sidetracked by APL to the line on which the locked function was invoked 
and the error report occurs on that line. 



System Functions Controlling Defined Functions 



CP-6 APL provides system functions which have the ability to create, modify, display, 
and set or query the attributes of defined functions. This section also introduces 
the terms nomelist and canonical representation which ore defined in Section 11 under 
the heading "Nomelist and Canonical Representations". The system functions covered 
in this section ore: 



UTRACE Set/query function trace attribute 

USTOP Set/query function stop attribute 

□CA Obtains function character representation 

UFX Creates or modifies a function 

UAT Query function attributes 



Each function is discussed in detail below. 
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UTRACE System Function (Tracing Execution) 



Syntax: 

R*UTRACE F 
R<-V UTRACE F 



Parameters: 

F is a namelist containing the name of a displayable defined function. 

Y is an integer or vector of integers that specify the line numbers for which 
execution results are to be displayed. Only the integers that correspond to line 
numbers in the named function are significant. 

R is an integer vector containing the original trace settings. 



Description: 

Function execution can be traced by displaying the results of statements (some or 
all) as execution of the function progresses. When any of the traced line numbers is 
executed, the result of its statements are printed. If the specified line contains a 
branch statement, a branch arrow followed by the new line number is printed. 
Specifying a trace vector of (lO) discontinues the trace. 



Examples: 

(tO)nrRACE *FAC' 
stops trace of function FAC . 

Below is an example of tracing the execution of a function. Notice that all output 
resulting from a trace is identified by the function name and line number. 

^Z^FAC N 
111 Z^l 
12] ^{N^l)/0 
(3] Z<-H*FAC H-\ 
[4] 7 

1 2 3 UTRACE *FAC* 

FAC 0 
FACll] 1 
FAC12] +0 
1 

FAC 1 
FACll] 1 
FAC12] ♦0 
1 

FAC 4 
FACll) I 
FAC12] *iO 
f>lCIl] 1 
FAC12\ ■►to 
FACll] 1 
FAC12] *tO 
FACll] I 
FAC12] -^0 
FAC12] 2 
FAC13] 6 
FAC12] 24 
2k 

(10) UTRACE *FAC* 

1 2 3 
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The same function written as a compound statement produces the following trace 
output : 

[I] -^{NiZ^-D/O 0 Z<-N*FAC N-l^ 

1 UTRACE 'FAC* 

FAC 0 
FACll] ■t'O 
1 



FAC 1 
FACll] -►O 
1 



FAC k 


FACl 1 1 


■no 


FACll] 


-►lO 


FACl 1 ] 


♦ lO 


FACll] 


-►o 


FACll] 


0 2 


FACll] 


0 6 


FACll] 




24 





The dyadic UTRACE function requires that the right argument contain a valid name or a 
DOMAIN ERR is reported. The explicit result of dyadic UTRACE is an integer vector 
containing the original trace setting of the named function. 

Setting a trace vector can also be included as part of a defined function. For 
example, if the statement 1 UTRACE 'FAC* is included within the above function, line 
1 wi I I also be traced each time the function is invoked. More complex expressions 
can be used to produce conditional tracing. In such cases, the condition produces 
one or more values (line numbers) that ore the left argument of UTRACE. This 
generalization also applies to the stop vector described below. 

The )OBSERVE command, described in Section 8, extends the tracing facility. It 
permits the user to see not only the final result of a trace command, but every 
intermediate result occurring as APL executes a traced statement. 

The current trace settings may be obtained by the monadic execution of the UTRACE 
system function. In this cose, the right argument is the some as in the dyadic usage 
of UTRACE and the result is on integer vector containing the current trace settings. 
For example: 

UTRACE *FAC' 

1 

»• UTRACE 'FAC 

I 

UTRACE 'FAC 



Possible Errors: 

A RANK ERR is reported if: 

o the left argument (new trace settings) is not a scolar or vector. 
A DOMAIN ERR is reported if: 

o the left argument is not a simple array containing only integers. 
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USTOP System Function (Stopping Execution) 



Syntax: 

R*BSTOP F 
R^V nSTOP F 



Parameters: 

F is a namelist containing the name of a displayabie defined function. 

Y is an integer or vector of integers that specify the line numbers at which the 
function is to stop. Of course, only the integers that correspond to line numbers in 
the named function are significant. If 0 is an item of V, the function stops on 
exit. 

R is an integer vector containing the original stop settings. 



Description: 

A planned suspension of function execution, called a function stop, can be 
established by setting a stop control vector. This vector is set in the same manner 
that a trace control vector is set for a function trace. 

When each specified line number is reached, APL stops execution and prints the 
function name, the line number, and optionally the line about to be executed. 
Function execution is now in a normal suspended state (subject to USA setting), and 
can be terminoted or resumed by appropriate branching (see Suspending Execution). 
Specifying lO discontinues the stop control vector; for example, (tO) USTOP *FAC* 
discontinues any function stops in function FAC . The )REPORT system command is used 
to include the APL statements in the stop report. 



Examp I es : 

Below is an example of stopping execution of a function named CIRCLE: 

2 5 USTOP 'CIRCLE' 
CIRCLE 
CIRCLE12] 

Suspension activities 
♦2 

13 
10 
30 

CIRCLE 15] 

The explicit result of USTOP is an integer vector containing the original stop 
settings of the named function. Like the trace control vector, the stop control 
vector can also be used within a defined function to stop execution after a certain 
number of loops. Editing a line that has a trace or stop control set removes the 
control for that line. Deleting, copying the function from a saved workspace, or 
locking a function also deletes trace control and stop control vectors associated 
with a function. 

The current stop settings may be obtained by executing the USTOP function 
monadicolly. In this cose, the right argument is the same as in the dyadic usage of 
USTOP and the result is a simple integer vector of the current stop settings. For 
example: 



CE38-04 



USTOP 

System Function (Stopping Execution) 



7-25 



STOPS*{]STOP * CIRCLE' 
pSTOPS 

Z 

STOPS 

2 5 

USTOP 'CIRCLE* 

2 5 

USTOP 'CIRCLE' 



Possible Errors: 

A DOMAIN ERR is reported if: 

o the right argument does not contain a valid name. 
A RANK ERR is reported if: 

o the left argument (new stop settings) is not a scalar or vector. 
A DOMAIN ERR is reported if: 

o the left argument is not a simple array containing only integers. 



UCR System Function (Canonical Representation) 



Syntax : 

R^DCR F 



Parameters : 

F is a namelist containing the name of a displayoble defined function. 
R is a simple character matrix. 



Descript ion: 

The UCR system function is used to obtain the character representation of a defined 
function. The right argument must be a namelist containing the name of a single 
defined function. The result is a matrix containing the canonical representation of 
the function (if it is displayoble) or a 0 by 0 matrix if the name is not a defined 
function or not displayoble. 

The canonical representation of a function contains the function header in the first 
row, followed by the function lines in the remaining rows. 



Examples: 

pR*DCR 'FAC 

k 11 

R 

R^FAC N 
R^\ 

•^{Nii)/Q 
R^N>iFAC N-l 
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UFX System Function (Fix Definition) 



Syntax: 

R*-nFX CR 
R*-AT UFX CR 



Parameters : 

CR is a simple character matrix (or vector with carriage returns) containing the 
canonical representation of a defined function. 

AT is a scalar or four-item vector containing only the scalar values 1 or 0. 

R is a simple character vector containing the name of the function established or 
an integer scalar row index of CR. 



Descript ion: 

The UfX system function creates a defined function from its canonical form. The 
right argument must be a character matrix (or vector with carriage returns separating 
lines). The first row of the matrix must be a valid function header and the 
remaining rows must be valid function lines. The explicit result of this function is 
the name of the function that was established, or the integer row index of the line 
which caused the definition attempt to foil. 

Before the function is established. APL makes sure that the name is not currently in 
use for anything other than c defined function. A DOMAIN ERR is reported if the name 
is in use and not a defined function or if the right argument is not a simple 
character array. A RANK ERR is reported if the right argument is not a scalar, 
vector or matrix. If the name is currently a local symbol to an active or executing 
function, then this function will exist as a local function. 

When UFX is used dyodically, the left argument must either be a scalar or four— item 
vector of simple booleans (1's and 0's). The left argument specifies the execution 
properties of the defined function. The four properties in order are: 

1 . not di spl ayabi e 

2. not suspendoble 

3. not i nterruptable 

4. execution errors converted to DOMAIN ERR 

If 0 scalar is used as the left argument, all four properties ore set to that value. 
Setting all of the properties to 1 is the same as locking the function. 



Examples: 

p«*Drjr CR*-{ZH**R*-FAC W'),(0.51'*(V^/?<-l)/0 0 R^N^FAC N-l* 

3 

R 

FAC 

CR 
R*'FAC N 

■^{lf^R*i)/0 0 R^M*FAC N-l 

VFACIU]7 
R*'FAC N 

[11 ■►(^S«<-l)/0 0 R*N*FAC H-l 
7 
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DAT System Function (Function Attributes) 



Syntax: 



UAT NAMES 



Parameters: 



NAMES 



is 0 namelist containing the names of defined functions. 



is the simple scalar integer value 1. 2, 3, or 4. 



R 



is a simple matrix containing the requested function attributes. 



Desc r i pt 1 on : 

The system function UAT returns attributes for each function named in the right 
argument. When a function is created by function definition or by the QFX system 
function, four attributes specific to the function ore defined. The attributes 
include the valence of the function, the creation time, the execution properties, and 
the account which created the function. 

The right argument of the DAT system function must be a name list containing the 
names of the functions whose attributes ore to be returned. The left argument is an 
integer scalar in the range 1 through 4 whose value determines the attribute to be 
returned. The result is a matrix (or vector if the namelist is a vector containing 
one name) with one row for each name in the namelist. 

The left argument value and the associated attributes are: 

1 — Valences 

Three items indicating whether a result may be produced and the number of arguments. 
The first item is 0 if there is no result, or 1 if there is a result. The second 
item is 0, 1. or 2 for nilodic, monadic or dyadic functions. The third item is 0 and 
is reserved for future use. 

2 - Great ion Time 

A seven-item vector indicating the time that the function was created. The items are 
in the following order: year, month, day, hour, minute, second, and millisecond. 

3 - Execution Properties 

A four-item vector, indicating execution properties of this function. The first item 
is 1 if the function may not be displayed (QOR not permitted). The second item is 1 
if the function may not be suspended (by double attention or on error). The third 
item is 1 if the function is not interruptoble by a single attention. The fourth 
item is 1 if any execution error (non-resource) produces a DOMAIN ERR report. The 
action of locking a function sets all but the last of these properties to 1. The 
dyadic use of the QFX system function permits each of these properties to be set 
i ndependent ly . 

4 - Creator 

An eight-item character vector, indicating the account that created 
(or last modified) this function. 
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Examples: 

pR^l DAT *FAC' 

3 

R 

1 1 0 

2 cur 'FAC* 
1983 10 11 12 29 59 610 
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System Commands 



System commands allow the user to control the mechanical aspects of APL, and can be 

divided into three categories: 



Workspace Control 
workspaces . 



Commands - commands that affect the state of active and saved 



2. Inquiry Commands — commands that supply information about the active workspace. 

3. Communications Commands - commands that send messages to the computer operator 
and log the user off APL. 

System commands always begin with a right parenthesis and can be entered when the 
system is in execution mode or definition mode. By using the Execute operator (see 
Section 5), system commands can be embedded in an APL expression and in a function 
line. Thus, o system command can be placed under control of such expressions or 
functions. Only the first four letters of command names are significant. Name 
characters after the fourth are ignored. Thus )CLEA and )CLEAVAGE are both 
interpreted to be the )CLEAR command. Note that a blank must separate the command 
name and any following parameters; for example, )WIDTH 30 is not the same as 
)WIDTH30. A number of conventions are used in this section to describe the command 
formats . 

1. Uppercase letters and special symbols must be typed exactly as they appear 
(except that only the first four letters of a command are required, as noted 
above) . 

2. Lowercase letters are employed to indicate where in a command to substitute a 
name or numerical value. The meanings or the notations in lowercase letters are 
OS fol lows: 



account 
fid 



f name 
grpname 
I ist 

message 
n 

ob j name 
string 



User account. 

CP-6 file identifier of the form: 
name . account . password . 

Name can consist of up to 31 characters. 
Account and password can consist of up 
to 8 characters. 

Name of a function. 

Name of a group. 

List of names (of functions, variables, groups), 
separated by blanks. 

Actual message to computer operator. 

An integer value. 

Name of function, variable, or group. 

Any sequence of characters not including a blank 
or carriage return. If a string includes more 
than 79 characters, those past the 79th are 
ignored. Strings are used for range demarcation 
in certain commands. 



vname 



Name of a variable. 
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wsname A workspace name; can consist of up to 31 characters 

(letters, underscored letters and numbers) as long 
as the first character Is not a number. It has 
the some form as fid. 

The actual system commands are detailed later in this section, but first 

it is necessary to describe the concept of a workspace in order to understand 

how certain commands are used. 



Workspace Concept 

Each user has a storage area containing control information which can be saved for 
future use. 



Active Workspace 

Associated with each user is a storage area in the computer known as an active 
workspace. This active workspace contains the following: 

1. All control informotion currently applicable to the terminal session. 

2. The variables, functions, and groups entered for calculations and still active 
during the session. 

3. A state indicator that keeps track of the names of suspended and pendent 
functions and at what point they were interrupted. 

4. System variables that control several features of APL, such as index origin, seed 
for random number generation, line width, and number of significant digits 
(decimal places) printed. These system variables all assume default values when 
the user first invokes APL, but they con be respecified with system commands, or 
by assignment. 

When APL is Invoked, the active workspace is usually clear (that is, there is nothing 
in it except the default values of the parameters mentioned above in item 4). An 
active workspace con also be cleared with the system command )CLEAR. 



Saved Workspace 

An active workspace can be saved for future use with the )SAVE command. Once a 
workspace is saved, any user who knows the workspace name con load it as on active 
workspace using the )LOAD command. The workspace's variables, functions, and groups 
con be copied into on active workspace using the )COPY command. The workspace con 
also be dropped using the )DROP command (if file access controls permit). In 
addition, the names of saved workspaces in an account can be listed with the )LIB 
command . 
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Continue Workspace 



A line disconnect or either of the following commands cause the active workspace to 
be saved in the logon account: 

) CONTINUE 
KONTINUE HOLD 

The CONTINUE workspace is automatically loaded as an active workspace the next time 
the user invokes APL unless it is directed to load another workspace. In general, 
the CONTINUE workspace can be used the same as any other named workspace. It can be 
saved, copied, loaded, etc. However, it should only be used for temporarily saving a 
workspace, since another )CONTINUE command or line disconnect would save another 
active workspace over what was previously saved. That is, the previous CONTINUE 
workspace will be overwritten. 

Since the CONTINUE workspace is part of the user's logon account, it is subject to 
the granule restrictions imposed by an installation. If the user's account is near 
that limit, the CONTINUE workspace may not be saved, and the information in the 
active workspace may be lost if a line disconnect occurs (see User Accounts). The 
CONTINUE workspace is saved with its access controls set to restrict access of the 
workspace to the user who created it. 



Initiating an APL Session 

APL is invoked with the following IBEX command syntax: 
lAPL [fidl] [JON|OVER|INTO^ [fid2] [,fid3]] [(options)] 



Parameters: 

fid1 is a CP— 6 file identifier designating either a workspace to be loaded, or a 
file containing APL statements to be used as input. In either case, fid1 indicates 
"source input" (the current setting of M$SI). If fid1 is a workspace file or if fidl 
is not specified, then APL input will default to the terminal on-line or the default 
input device in batch (ME). The APL )SET INPUT command may be used to redirect input 
after entering APL. 

ON specifies that if fid3 already exists, the file is not to be overwritten. An 
error is reported. 

OVER specifies that fid3 is to be overwritten even if it currently exists. 

INTO specifies that APL output is to be appended to the end of file fid3 (if it 
ex i sts) . 

fid2 is the CP-6 file name that is to be used by APL to designate the CONTINUE 
workspace name (the current setting of M$OU) . If not specified, the CONTINUE 
workspace name defaults to the string 'APL:' followed by the current user's logon 
name (established when logging onto CP-6). The account used to hold the CONTINUE 
workspace is always the logon account. APL uses this file identifier in the event of 
0 line disconnect, an uncontrolled error, or a limit exceeded error in batch mode, or 
if a )CONTINUE command is issued. 

fid3 is the CP-6 file identifier that specifies the file containing output 
generated by the APL session (the current M$LO setting). If fid3 is not specified, 
then APL output will default to the terminal on-line and the line printer in batch. 
The APL )SET OUTPUT command may be used to redirect output after entering APL. 

options is the list of APL options to be used for this session separated by 
commas. The options permitted are QUIET, WS, and CPV . The QUIET option invokes APL 
without the initial version and either CLEAR WS or SAVED messages being displayed. 
The WS option must be followed by = and a fid which identifies a workspace to be 
automatically loaded. If the WS option is specified, then fidl must contain the APL 
statements to be executed. The CPV option causes some of the primitive functions in 
CP-6 APL to perform as their counterparts in CPV APL performed. 
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User Accounts 



Accounts are specified when logging onto CP-6 or when accessing files in accounts 
other than the default file management account for a user. CP-6 installations impose 
restrictions on file allocation spoce (and file access) of file management accounts. 
When on account is at (or very near) its space limit, other files (or workspaces) In 
the account may need to be deleted to create or update a file (or workspace). In 
this event, APL reports the error. The )? command con be used to obtain more 
information about the error. 



Commeuid Processor 



The material which follows assumes that the Command Processor in effect when APL is 
invoked is the CP-6 IBEX processor. If this is not the cose, the commands )CONTIHUE, 
)!i )OFF and )SET may operate in a manner other than specified here. In particular, 
for the transootion processing command processor (TPCP), some of these commands will 
result in the BAD COMMAND error. 



System Command Summary 

The system commands are detailed below in alphabetic order, and are summarized by 

category in Table 8-1. 



Table 8-1. System Command Summary 



Command Descript ion 

Workspace Control Commands 



)CATCH [vname VIA name] 

Removes any current catches (i.e., intercepts of assignments to 
specified variable names) or designates that assignments to vname ore 
to be "caught" (intercepted immediately after the assignment), and 
that the test function name, a ni Iodic function or character vector, 
is to be executed. 



)CLEAR 

Clears active workspace and restores default width, print precision, 
index origin, comparison tolerance, random number link, etc. 



)COPY fid [I ist] 

Copies functions, variables, and groups from saved workspace. Any 
password must be included, and so must the account if different than 
the file management account. If list is present, then only those 
named ore copied. If list is not present, all names in fid ore 
copied. 
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Table 8-1. System Command Summary (cont.) 


Command 


Description 




Displays the current value of UPP (numeric print precision). If n is 
specified, sets the value of UPPi and displays the previous value of 
UPP. 


)DROP [fid] 


Deletes a saved workspace. If the file identifier Is protected with 
a password, the 


) ERASE list 


Removes the named objects such as functions, variables, or groups 
from active workspace. 


)GROUP grpname [list] 




Groups objects and names the group. If list is not specified, 
disperses the named group. 


)LOAD fid 


Moves 0 copy of the saved workspace into the active workspace. If 
the file identifier is protected with a password, the password must 
be specified. Also, if the saved workspace is in another account, 
that account must be specified. 


) OBSERVE 


Specifies that the next (direct input) statement and any traced 
function statements executed are to be "observed". This displays a 
number of "observations", showing intermediate results as APL 
intemrfits those statements 


)ORIGIN [n] 


Displays the current value of D/O (the index origin). If n is 
specified, sets the value of Q/O where n con be 0 or 1. and displays 
the previous value of Q/O. 


)PCOPY fid [ 


ist] 

Same as )COPY, except that a name is not copied if it already has a 
value in the active workspace. 


)QCOPY fid [ 


ist] 

Some OS )COPY , except that the SAVED message is suppressed, i.e., 
quiet copy. 
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Table 8-1. System Command Summary (cont.) 


Command 


Descr ipt ion 


)QLOAD fid 


Same as )LOAD, except that the SAVED message is suppressed, i.e., 
quiet load. 


)QPCOPY fid [list] 




Same as )PCOPY, except that the SAVED message is suppressed, i.e., 
quiet copy. 


) SALVAGE fid 


[list] 

Similar to )COPY except objects may be copied from broken workspaces. 


)SAVE [fid] 


Saves the active workspace. If fid is specified, saves active 
workspace under the specified name. To save a workspace and protect 

11 w 1 i, n u pusswo ru f i o i i ow i nc wu r Kspucc nurnc w i i n iwo r i oas unu 

the password name (i.e.» )SAVE wsname . .password) . 


)SEAL [fid] 


Saves the current workspace as a sealed 'execute-only' workspace with 
inc ucsiynuicu nunic. 


)WIDTH [n] 


Displays the value of UPV (the current maximum width of output 
lines). If n is specified, the value of []P(/ is changed, and the 
previous value of QPW is displayed. The width parameter n con range 
from 32 to 390. 


)WSID [fid] 


Displays the file identifier of active workspace. If fid is 
specified, assigns the file identifier to active workspace, or 
changes the name if one already exists and displays the old name. 


Inqui ry and 


Communication Commands 


)CONTINUE [OATlO/'/'l [HOLD] [fid]] 




Ends terminal session, and saves the active workspace as a CONTINUE 
workspace. If HOLD is specified, returns control to the CP-6 IBEX 
command processor. If OFF is specified, suppresses automatic 
generation of CONTINUE workspace file. If OH is specified, 
reinstates such automatic generation. If fid is specified, it 
overrides the default CONTINUE workspace name. 
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Table 8-1. System Command Summary (cent.) 



Command Descr i pt ion 



) ED I TOR [CPeRR\STD\SE] 



)END 



Displays the current editor. If CP6RR is specified, the CP-6 re-read 
mode of editing APL lines in definition mode is used when a [line □ 
position] directive is encountered. 

If STD is specified, APL "super-edit" mode of editing APL lines in 
definition mode is selected. This is the editing method most often 
available on other APL implementations. 

If SE is specified, APL uses the CP-6 screen editor. 



Returns control to CP-6 IBEX, 



) ERROR [BRIEF I FULL I SUMMARY] 



Displays the current error message information level. If BRIEF is 
specified, the most concise error messages for error displays are 
selected. If SUMMARY is specified, one-line error messages for error 
displays are selected. If FULL is specified, the most informative 
error messages for error displays are selected (possibly multi-line 
error messages) . 



)FNS [stringl [string2]] 



)G0 



)6RP name 



Alphabetically lists all defined function names in active workspace. 
CP-6 APL uses the following collating sequence in the process of 
a I phabet i z i ng : 

o blank or end of name 
o digi ts 

o alphabetic letters without underlines (A through Z) 
o under I i ne 

o underlined alphabetic tetters (A through Z.) 
o A» ^ 

If stringl is specified, the list of names starts at the first name 
which is alphabetically equal to or greater than stringl. If string2 
is specified, the list of names ends before the first name 
alphabetically greater than 8tring2. 



Resumes execution at the current line. 



Lists the names in the specified group. 
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Table 8-1. System Command Summary (cent.) 



Commend Peso ript ion 



)GRPS [stringi [string2]] 

Alphabetically lists all group names in active workspace. CP-6 APL 
uses the following collating sequence in the process of 
a I phabet i z i ng : 

o blank or end of name 
o digits 

o alphabetic letters without underlines (/ through Z) 
o underlined alphabetic letters (A through 2) 
o 4> ^ 

If stringi is specified, the list of names starts at the first name 
which is alphabetically equal to or greater than stringi. If string2 
is specified, the list of names ends before the first name 
alphabetically greater than string2. 



)IBEX message 

Issues command to IBEX. 



)LIB [account] 

Lists the names of saved workspaces in an account. 



)NMS [stringi [string2]] 

Alphabetically lists all of the global names in use and their name 
class in the active workspace. The stringi and string2 parameters 
are used in the same way as the )FNS command. 



)OFF [HOLD] 



Ends the terminal session and discards the active workspace. If HOLD 
is specified, control returns to CP-6 IBEX, otherwise the user is 
logged off of CP-6. 



)OPR message 








Sends message 


to computer operator, and waits for a reply. 


)OPRN message 








Sends message 


to computer operator. 


)QUIT 








Same as )ElfD. 
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Table 8-1. System Cofflmand Summary (cent.) 



Command Descript ion 



)REPORT [FUNC[TION]|L/A^£'] 

If FUHCTIOH is specified. APL displays the function name and line 
number when a function is stopped (default). If LINE is specified. 
APL displays function name, line number and the contents of the line 
when a function is stopped. 



) RESET 

Completely clears the state indicator. Same as )SIC. 



)SET deb fid 

Allows routing of regular output, input and/or 'blind' I/O channels 
to files or various devices, and specification of formatting options 
for device output. Analogous to the SET command in CP-6 IBEX. 



)SI [Olf\OFF\CLEAiRU 

Lists the contents of the state indicator, a list of suspended and 
pendent functions. If CLEAR is specified, clears the entire state 
indicator. If OFF is specified, prevents an error from suspending 
the function containing the erroneous statement. If ON is specified, 
restores normal state indicator control. If an error occurs in an 
active function line. APL suspends the function at that line 
(assuming sidetracking does not occur, see section 10). 



)SIC 

Completely clears the state indicator. Some as )RESET. 



Lists contents of the state indicator, a list of suspended and 
pendent functions, and the contents of lines in execution. 



)SINL [ON\OFF\CLEA[R]] 

Lists the contents of the state indicator, a list of suspended and 
pendent functions, and the local voriables named by those functions. 



)SIV [ON\OFF\CLEA[R]'\ 

Same as )SIHL. 



)STEP [LIHE\FUNC[J1(M]] [n] 

Executes the line indicated by the top entry in the state indicator, 
and stops before any other line is executed. If the FUNCTION 
parameter is specified, the stop will not count function lines in 
functions invoked by the line initially put in execution. The LINE 
parameter is the default, and it causes APL to stop before any other 
line is executed. The n parameter specifies the number of lines to 
execute before stopping. 
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Table 8-1. System Command Summary (cont.) 



Command Descript ion 



)TERMINAL [ INPU[T] I OI/rP[UT] ] [n] 

Identifies to APL the input/output devices being used, where n con be 
any of the following values: 

1,13,14 for devices with APL 
character set 

2,3,4,5 for devices with ASCII 
character set 



)VARS [stringi [string2]] 

Alphabetically lists alt global variable names in active workspace. 
CP-6 APL uses the following collating sequence in the process of 

a I phabet i z i ng : 

o blank or end of name 
o digits 

o alphabetic letters without underlines {A through Z) 
o underlined alphabetic letters through Z) 

o ^, ^ 

If stringi is specified, the list of names starts at the first name 
which is alphabetically equal to or greater than stringi. If string2 
is specified, the list of names ends before the first name 
alphabetically greater than or equal to string2. 



)? 

Displays the next highest detailed error message (if any) about the 
most recent error condition. 



)CATCH Intercepting Assignments 



Syntax : 

)CATCH [vname VIA name] 



Parameters: 

vname is the name of the variable (which may be local or global), 
name Is the name of a function or character vector. 
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Description: 

The )CATCH command is primarily a debugging tool. It permits the programmer to 
intercept each assignment to a specified variable name, immediately after that 
assignment is completed. The function is defined according to the user's debugging 
needs. The only restriction is that this name must be a character vector or 
represent a ni Iodic function with no result. This restriction isolates the name from 
the statement or statements assigning values to the specified variable. If the name 
is undefined or does not indicate a character vector or a ni Iodic, no— result 
function, no error message occurs; the catch is simply ignored. Catches on shared 
variables are not permitted. 

Catches are not saved when a workspace Is saved, so loading a workspace does not 
automatically reinstall catches. The )CLEAR command also removes any current 
catches. The )CATCH command without options removes any existing catches. A maximum 
of two catches can be defined at one time. 



Examples: 

Suppose the programmer has invoked the following catch, 
)CATCH VI VIA Fl 

then all assignments to the name VI cause function fl to be called or If Fl is a 
character vector, the expression iFl Is executed. This includes indexed assignments. 
Fl is executed regardless of whether VI Is a local or global variable. The 
programmer con modify this catch to enter a different test function. For example. 

)CATCH VI VIA FTWO 

After the above specification, assignments to VI cause test function FTWO to be 
called (instead of fl). 

The programmer con also invoke a second catch. For instance. 



)CATCH VAR2 VIA FOTHER 

The programmer can hove both catches enter the same test function as in the next 
example. 

)CATCH VAR2 VIA FSAHE 
)CATCH VI VIA FSAME 

The programmer cannot, however. Invoke a third catch; this attempt produces a BAD 
COMMAND error. 

Any current catches can be removed by issuing the command 
)CATCH 

Following this command, the programmer is free to specify one or two new catches. 

The simplicity of the )CATCH command may obscure its power as a debugging aid. This 
power is brought to bear by the test expression. A few hypothetical examples are 
given below to suggest the potential of catch capability. 

Using a catch to display values assigned to vnome: 

)CATCH X VIA SHOWX 
SHOWX^' "X IS 0X0 • 



As long as the catch is in effect, every assignment to A" wi I I cause the new value of 
X to be displayed. A catch may be used to stop execution when a particular value is 
assigned to a name. (Assume that X \9 a scalar and 77 is the value of interest.) 
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)CATCH X VIA CHECK 
VCHECK 

[1] *(;i:k77)/o 

(21 STOP OsrOP 'CHECK' 
12] STOP'.V 

As long as this catch is in effect, each assignment to AT wi I I be tested at line 1 of 
the CHECK function. If X is not 77, line 1 causes CHECK to exit. If X receives the 
value 77, line 2 is executed. Line 2 sets the stop— vector for the CHECK function so 
that when the line labeled STOP is reached. CHECK will suspend execution. 

Using a catch to change the value of vname: 

(Note that this does not affect the value used by the statement making an assignment 
to vname; the catch is isolated.) 

)CATCH X VIA CHANGE 
VCHAHGEiCHANGE 
tl] X^O ^ 



As long as this catch is in effect, each assignment to X that occurs "outside" the 
CHANGE function will cause X to be set to 0. The assignment at line 1 of the CHANGE 
function will not be "caught" because calling the function temporarily declares the 
name CHANGE to be a local variable (shadowing the definition of CHANGE as a test 
function); see the function header line. 

Suppose the following stotement is executed with the above catch in effect. 

jr + 100 + ;r*55 

The answer of 155 results in the following way. 

1. The value 55 is obtained. 

2. X is assigned the value 55. 

3. The catch occurs. 

4. is set to 0 by the CHANGE function. 

5. Execution of the original statement resumes, undisturbed (so far. at least) by 
the catch. This means that the value 55 is the right argument of the next 
oddi t ion. 

6. 100 plus that argument yields 155. 

7. This value, 155, becomes the right argument of the next addition. 

8. The value of X is obtained; it is now 0. 

9. 0 plus 155 yields the final result. 
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)CI_EAR Clearing Workspace 



Syntax: 
) CLEAR 

Descr i pt ion: 

The )CLEAR command deletes all groups, functions, variables, and the state indicator 
from active workspace. Furthermore, it resets the following system variables and 
workspace attributes to the values in parentheses: 

o Random number link (16807). URL 

o Comparison tolerance (1£~13). OCT 

o Index origin (1). QIO 

o Platen width (terminal dependent). UPW 

o Significant digits (10). DPP 

o Workspace identification (CLEAR WS) . 

o Latent expression ("). QLX 

o Stop action ("). USA 

o State indicator control (ON); see also the )SI command description. 

o Current catches (none), see the )CATCH command description. 

o Error number (0) , see Sidetracking on Errors and Breaks in Section 10 

o Error location (line number 0 and function name on empty character vector). (See 
al so Sect i on 10) . 

APL responds to this command by printing the message CLEAR WS. 

Exomp I e : 

)CLEAR 
CLEAR VS 

)CONnNUE Saving Active Workspace and Leaving APL 

Syntax: 

KOHTIHUE [[0H\0FF\\.H0LD'\[i\6'\'\ 
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Parameters: 



fid overrides the default CONTINUE workspace name. 

HOLD causes APL to exit to IBEX rather than logging off. 

ON specifies reinstatement of automatic generation of the CONTINUE workspace 
f i le. 

OFF specifies suppression of automatic generation of the CONTINUE workspace file. 



Descript ion: 

The )COHTINUE command soves the active workspoce in a CONTINUE workspace, and logs 
the user off. This workspace is automatically loaded the next time the user invokes 
APL without specifying a workspace. The active workspace is also automatically saved 
OS a CONTINUE workspace if the terminal is accidentally disconnected or other 
unexpected end of session (LIMIT exceeded, unexpected error, etc.) occurs, unless 
such automatic action is suppressed (see below). 

A successful )CONTINUE command will produce a save report (time and date saved) and 
the CP-6 log off messages. If insufficient room remains in the user's account to 
save the workspace. APL prints on error message. If this happens, the user must 
delete some workspaces or other files before any APL workspaces may be saved. 

The default CONTINUE workspace name con be overridden at APL invocation time or by 
appending a fid to the end of either form of this command. See "Initiating on APL 
Session" for more details on the continue workspace name. 

NOTE: If a user's workspace is passworded. the password is retained in the CONTINUE 
workspace. In this cose, the CONTINUE workspace is not automatically loaded the next 
time the user logs on. 

If on account already contains a passworded CONTINUE workspace, any subsequent 
CONTINUE will foil until the passworded version is deleted. Sealed workspaces cannot 
be saved with CONTINUE. 

If either form of the )CONTINUE command is given during function definition mode, the 
currently open function is closed by APL. When the CONTINUE workspace is loaded 
later, APL automatically reopens the function and prompts the user to continue 
function definition. The automatic saving of this workspace can be suppressed by 
issuing KONTIHUE OFF. It can be reinstated by issuing )CONTINUE ON. 

The CONTINUE workspace con be used almost like any other named workspace. It con be 
saved, copied, loaded, etc. However, the default name should only be used for 
temporarily saving a workspace since any CONTINUE workspace can be erased by a new 
CONTINUE workspace save. 



Examples: 

)CONTINUE 

APL-.ZOIGEISERT SAVED 15:33 DEC 15 '8<( 

Saves active workspace and ends terminal session after printing save report and CP-6 
log off messages. 

KONTIHUE HOLD 

APLtZOiGEISERT SAVED 15:31 DEC 15 '84 
f 

Saves active workspace and returns control to command processor after printing save 
report. IBEX prompts for commands with the I character. 
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)COPY Copying from Saved Workspace 



Syntax: 

)COPY fid [list] 



Parameters: 

fid is a CP-6 file identifier of a saved workspace. 

list is a list of variable names, function names, or group names, separated by 
b I anks . 



Description: 

The )COPY command copies information from a saved workspace into the active 
workspace. The information can consist of one, several, or all of the functions, 
global variables, and groups in the saved workspace. If the list parameter is not 
specified, all of the global names in the saved workspace are copied (except for 
system variables). 

Note that if a workspace is saved with a password, that password must be included in 
the )COPY command. Also, if a workspace is copied from another user's account, the 
account must be specified in the )COPY command. 

When a saved workspace is copied, only global functions, global variables, and groups 
are copied. If copied functions had sidetracks (see Section 10). then these settings 
also apply in the active workspace. All referents of a copied group are themselves 
copied into the active workspace. For instance, suppose group Gl is copied, where CI 
contains A, B, and G2 with G2 being another group containing X, Y, and Z. Then the 
following are copied into the active workspace: Gl, G2, A, B, X, Y and Z. The state 
indicotor and system variables ore not copied. (Most system variables con be copied 
by specifically naming them.) 



A copy attempt may fail if there is not enough room in the active workspace to hold 
the items copied. In that cose, an error message is displayed and the workspace will 
contain the same objects it contained before the )COPY command was issued. The error 
message TOO BIG TO LOAD is displayed when copying from a different account in which 
two conditions are met. First, the workspace copied from is large (so large that it 
could not even be loaded by the current user). Second, the referenced account is 
allocated more computer memory than is available to the current user's account 
(memory allocations ore specified by the installation manager). This difficulty con 
be circumvented with the cooperation of the owner of the larger account, who con copy 
portions of the large workspace, forming one or more smaller workspaces. After this 
cooperative activity, the current user can copy required objects from those smaller 
workspaces. 

If a )COPY command is issued during function definition mode, the currently open 
function is temporarily closed. When the copy is completed, the function is 
automatically reopened. The copy may hove replaced the current function. If the 
)COPY command names functions that are pendent in the active workspace, they are not 
replaced. Suspended functions may be replaced and may cause an SI DAMAGE error 
message to be issued. Use of the )PCOPY command precludes this possibility. 



The )PCOPY command is the same as the )COPY command except that an object is not 
copied if the active workspace already contains on object with the same name. 

A group of objects can be copied even though the group definition is not copied. 
This happens if the group name matches the name of a pendent function in the active 
workspace or if the name matches any object in the case of )PCOPY. Alternatively, a 
group definition may be copied but some of its objects not copied. 
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Examples: 

)COPr GRAMOLA . ACCTZ2 .SECRET 
GRANOLA SAVED 15:08 DEC 15 

Copies a saved workspace named GRANOLA. and prints a save report giving the time and 
date GRANOLA was saved. The workspace GRANOLA is saved with the password SECRET in 
another user's account (account ACCT33). 

)COPY KAWA 
KAWA SAVED 15:00 DEC 15 *84 

Copies an entire saved workspace named KAWA from the user's own account and produces 
0 save report giving the time and date KAWA was saved. 

)COPY WS ATMF CHEAP UPP 
WS SAVED 13:31 DEC 01 '9k 

Copies o function named ATMF, a group named CHEAP, and the system variable UPP from a 
saved workspace named WS in the user's own account. A save report giving the time 
and dote WS was saved is printed. 

)COPY HENRY. .SECRET 
HENRY SAVED 15:08 DEC 15 'B* 

Copies a saved workspace named HENRY, and prints a save report giving the time and 
date IHENRY was saved. The workspace named HENRY is saved with the password SECRET in 
the current user's account. 

If the )COPY command is used to access a workspace sealed by another user, the error 
message SEALED WS is reported. 



)DIGITS Specifying Numeric Print Precision 



Syntax : 
)DIGITS [n] 



Parameters: 

n indicates the new value for UPP (the number of significant digits in printed 
output) which con be any integer number from 1 through 20. APL then prints the 
previous value of UPP' If n is not specified, APL prints the current value of UPP' 



Descript ion: 

The )DIGITS command sets the number of digits in numeric output to a number between 1 
and 20 inclusive. The default value in a CLEAR WS is 10, which displays a maximum of 
10 significant digits. Only numeric output and the result of the monadic v function 
are affected by this command; internal calculations are not affected. 



Examples: 

)DIGITS 
IS 10 

This requests the value of UPP to be displayed. APL responds with the current value. 

)DIGITS 15 
WAS 10 

This sets the value of UPP to 15. APL responds with the previous value. 
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Here, the result of a calculation is printed. APL displays the value to 15 
significant digits. 

)DIGITS 5 
WAS 15 

This sets UPP digits to 5, and APL responds with the previous value. 

The result of an expression is displayed again, showing 5 significant digits. 

The number of significant digits to be output can also be changed by redefining the 
value of QPP. 



)DROP Dropping a Saved Workspace 



Syntax: 
)DROP [fid] 



Parometers: 

fid is a CP-6 file identifier (omission of fid implies the default CONTINUE 

workspace) of a saved workspace. 



Descr i pt i on: 

The )DROP command removes a saved workspace. It has two forms, one for removing 
unprotected workspaces, and another for removing the default CONTINUE workspace. If 
the workspace is not found, delete access is not available, or the proper password is 
not provided, APL returns the message WS NOT FOUND. If the workspace is deleted. APL 
returns a message identifying the workspace and the time it was last saved. 



Examples: 

)DROP GRANOLA. .SECRET 
ORANOLA SAVED U:58 DEC 15 •8'l 

Removes the workspace GRANOLA with password SECRET, from the user's account. 
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)EDITOR Selecting the APL Function Editor 



Syntax : 

) ED I TOR [CP6RR\STD\SE] 



Parameters: 

CP6RR selects the CP-6 re-read mode of editing APL lines in definition mode when 
a [line D position] directive Is encountered. 

STD selects APL "super-edit" mode of editing APL lines in definition mode. This 
is the edi t i ng method most often available on other APL implementations. 

SE selects the CP-6 APL screen editor. It is available for most CRTs that may be 
connected to the CP-6 system. The terminal profile must indicate RETYPOVR^YES and 
EDITOVR=YES. 



Descr ipt ion: 

The )EDITOR command permits the APL user to choose the edit mode of line editing for 
the [line □ position] directive. If a mode is not specified, the current editor 
setting is displayed. CP-6 re-read mode is by far the more powerful line editing 
technique, but super edit mode is included for compatibility with other APL 
imp I ementat i ons . 

Super edit is a two pass editing method. In this mode, the line is displayed and APL 
awaits input on the line following at the position specified. Blanks or backspaces 
may be entered to position. The digits 0 through 9 insert that number of blanks, the 
letters A through Z insert 5, 10, 15,... blanks. A slash "/" is used to delete 
characters. A decimal point "." inserts all of the characters following it. 

The line is re-displayed with all of the character insertions and deletions and the 
cursor is positioned at the first insertion position. Now all of the normal CP— 6 
line editing capabilities ore available to modify the line. 



Examples: 

) ED I TOR STD 
WAS CP6RR 
VFUN 

[I] a THIS IS A TET OF SUPER EDIT 
[1] [10 20] 

[1] 0 THIS IS A TET OF SUPER EDIT 
I 

[ 1 ] 0 THIS IS A TEST OF SUPER EDIT 
121 V 
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)END Exiting APL 



Syntax: 
)END 



Description: 

The )EHD command causes the contents of the active workspace to be discarded, 
following which control is passed to the process which invoked APL. This is usually 
IBEX, the CP-6 Command Processor. This command is functionally identical to the 
)OFF HOLD command. 



)ERASE Deleting Objects From Active Workspace 



Syntax: 
)ERASE I ist 



Parameters: 

list specifies the names of the global objects (i.e.. functions, variables or 
groups) to be erased. Note that it is the value that is erased; the name may remain 
in the symbol table. 



Description: 

The )ERASE command deletes one or more named objects (i.e.. global functions, global 
variables, or groups) from the active workspoce. If a group is named in the )ERASE 
command, that group definition is erased along with any functions, groups, or 
variables named in the group. Pendent functions cannot be erased. It is impossible 
to erase a locked function in a sealed workspace. During function definition, if the 
function being defined is erased, definition mode is abandoned (equivalent to closing 
the function and then erasing it). 



Examples: 

)ERASE HATHFUNCTIONS 

Erases a group named HATHFUHCTIONS and the functions and variables it names. It 
disperses any group named within the group HATHFUNCTIONS . 

)ERASE PAYROUTIHE GROSS INS 

Erases a function named PAYROUTINES and two variables named GROSS and IHS. 

NOTE: The )ERASE command will not remove local variables. 
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)ERROR Selecting Error Message Information Level 



Syntax: 

)ERROR IBRIE[F]\FULL\SUMMIARY]] 



Parometers: 



BRIEF selects the most concise error messages for future error displays. 

FULL selects the most informative error messages for future error displays 

(possibly multi-line error messages). 

SUMMARY selects one-line error messages for future error displays. 



Descript ion: 

The )ERROR command selects the default error message information level. APL error 
messages ore often available in various levels of information. The most concise 
messages ore known as BRIEF. This type includes DOMAIN, RANK, LENGTH, and other 
general messages. These messages often contain sub— d i v i s i ons which provide 
information specific to this instance. These sub— di vi si ons are known as SUMMARY and 
FULL. SUMMARY messages are typically one line and FULL messages con contain up to 
seven lines of error message text. The )? command may be used to obtain additional 
error information after an error has been reported. 



Examples: 

)ERROR SUMMARY 
WAS BRIEF 



5^0 

DIVISION BY ZERO 

A 

)ERROR FULL 
WAS SUMMARY 



12 + 123 
THIS FUNCTION REQUIRES THAT BOTH ARGUMENTS 
HAVE THE SAME SHAPE {DIMENSIONS) OR THAT AT 
LEAST ONE ARGUMENT IS A SINGLE ELEMENT ARRAY. 

12+12 3 

A 



) ERROR BRIEF 
WAS FULL 

12+12 3 
LENGTH ERR 

12+12 3 

A 
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)FNS Listing Global Function Names 



Syntax: 

)FNS [stringi [strlng2]] 



Parameters: 

stringi is any sequence of characters not including blank or carriage return. 
string2 is any sequence of characters not including blank or carriage return. 



Descr i pt i on: 

The )rNS command alphabetically lists the names of functions In the active workspace. 
If stringi is specified, all function names that are alphabetically equal to or 
greater than stringi and are also less than or equal to string2 are displayed. If 
stringi is not specified, all function names are displayed. Alphabetic ordering is 
illustrated in the examples. Note particularly the first )FNS command since it 
indicates where each name character lies in alphabetic order. 

If a string includes more than 79 characters, those post the 79th ore ignored. 
Strings ore only used for range demarcation in an alphabetic ordering. 



ExampI es: 

)FNS 

F FO Fl FF FX FXY FE F^ FL S T 
)FNS FF 

FF FX FXY FE F^ FL S T 

)FNS F FF 
F FO Fl FF 

)FNS FFF FX 

FX 

)FNS FXY FXY 

FXY 

) FNS A Z 

F FO Fl FF FX FXY f£ F^ FL S T 



)G0 Resume Execution 



Syntax: 
)G0 
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Descript ion: 

The )G0 command resumes execution of the most recently suspended function at the 
start of the current line. 



)GROUP Creating a Group 



Syntax: 

)GROUP grpname [list] 



Parameters: 

grpname is the name of the group. A group name follows the same formation rules 

OS a variable or function name, except that a group name cannot be the same os a 
global function or global variable in the active workspace. 

list is a list of the names that make up the group, separated by blanks. 



Description: 

The )GROUP command references a group of names, i.e., variables, functions, other 
groups, or just names collectively. Group definitions can be used in )ERASE and 
)COPY commands to facilitate erasing and copying a group of related objects. Names 
can be added to on already existing group by merely repeating the group name in any 
of the command forms: 

)GROUP grpname grpname list 
)GROUP grpname list grpname 
)GROUP grpname list grpname list 

A group can be dispersed with the command form 

)GROUP grpname 

This form disperses the group; that is, removes the name references previously 
associated with grpname. The names and their references ore not themselves erased, 
only the group identity is lost. An )ERASE command can be used to remove the group, 
but the )ERASE command removes the group and deletes the group referents (the actual 
functions or variables) from the active workspace. 



Examples: 

)GROUP PROBX COS TAN A B 

Defines a group named PROBl, consisting of the variable and functions named COS, TAM , 
A, and B. 

)GROUP PROBl PROBl D ST 

Adds the variable D and ST to the already existing group named PROBl. 

) GROUP PROBl 

Disperses the group named PROBl from the octive workspace. The referents of PROBl 
ore not deleted. 

Note that the last example disassociates the function and variable names from the 
group, but does not delete actual functions and variables from the active workspace. 
The )GRPS command con be used to verify that the group named PROBl has been deleted, 
and the )FHS and )VARS commands can be used to verify that the named function and 
variables still remain in the active workspace. 
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)GRPS 

)FNS 
COS TAH 

)VARS 
A B C ST 

Also see the )GRP and )GRPS commands, which list the members of a group and the names 
of groups in active workspace respectively. 



)GRP Listing Members of a Group 



Syntax: 
)GRP name 



Parameters: 

name is the name of a group. 



Descr i pt ion: 

The )GRP command prints all of the names contained in the specified group. 



Exompl es: 

)GROUP G\ A B C 

)GRP Gl 
ABC 

)GROUP Gl Gl D 

)GRP Gl 
A B C D 

)GROUP Gl X Y Z Gl G2 

)GRP Gl 

XYZABCDGZ 

)GROUP GZ X A Fl 

)GRP GZ 
X A Fl 

)GRPS 

Gl GZ 

)GROUP Gl 
)GRPS 

GZ 

)GRP Gl 
)GRP GZ 
X A Fl 
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)GRPS Listing Names of Groups 



Syntax: 

)GRPS [stringi [string2]] 



Parameters: 

stringi is any sequence of cliaracters not including blanic or carriage return. 
string2 is any sequence of characters not including blank or carriage return. 



Descr ipt ion: 

The )GRPS command alphabetically lists the names of groups in the active workspace. 
Alphabetic ordering is illustrated in the examples. Note particularly the first 
)GRPS command since it indicates where each name character lies in alphabetic order. 

If stringi is specified all group names that ore alphabetically equal to or greater 
than stringi ore displayed. If stringi is not specified, all group names ore 
displayed. If o string includes more than 79 characters, those past the 79th ore 
ignored. Strings ore only, used for range demarcation in alphabetic ordering. If 
string2 is specified, all group names that ore alphabetically equal to or greater 
than stringi, and are also less than or equal to string2 are displayed. 



Examples: 

)GRPS 

G GO Gl GG GH GHI GQ G& GL H 

)GRPS GG 
GG GH GHI GQr GL GL H 

)GRPS G GG 
G GO Gl GG 

)GRPS GGG GH 

GH 

)GRPS GHI GHI 

GHI 

)GRPS A Z 
G GO Gl GG GH GHI GQ C4 GL H 



)IBEX Issuing CP-6 Commands 



Syntax: 

)IBEX message 
) imessage 



Parameters: 

message specifies text of o legal IBEX command. 
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Descri pt ion: 

The )! command directs o string of characters to the CP-6 Command Processor (IBEX) 
for further processing. 



Examples: 

)IBEX DI 
USERS = 63 
ETMF = 1 

90p RESPONSE < 100 MSECS 
DEC 15 'Bk 15:10 

)IDI 
USERS = 63 
ETMF = 1 

90p RESPONSE < 100 MSECS 
DEC 15 '84 15:11 



)LIB Listing Names of Saved Workspaces 



Syntax: 

)LIB [account] 



Parameters: 

account specifies a CP-6 account name. 



Descri pt ion: 

The )LIB command lists the names of workspaces saved in an account. If a password 
was saved with a workspace, the workspace name is listed, but not the password. 



Examples: 

)LIB 
APLaUIZ 
APLSIDR 
PROBi 
PROBZ 

Lists names of saved workspaces in the current user's account. 

)LIB REI 07207 
EDITFILE 
FACTOR 
PAYROLL 

Lists names of saved workspaces in another account (account REI07207). 
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)LOAD Retrieving a Saved Worl^space 



Syntax: 
)LOAD fid 



Parameters: 

fid is the CP-6 file identifier of a saved workspace. 



Descript Ion: 

The )LOAD command causes a copy of saved workspace to be loaded into the user's 
active workspace. The saved workspace may be retrieved from a user's own account or 
another account. Note that if a saved workspace Is retrieved from another account, 
the account must be specified in the )LOAD command. Also, if the workspace is saved 
with a password, that password must be included In the )LOAD command. In response to 
a successful load, APL prints a message giving the time and day that the workspace 
was saved. If the workspace is not found or if a proper password is not used, APL 
prints the message WS HOT FOUND. After a successful )LOAD the expression sQLX is 
executed . 

If a workspace is saved during function definition mode, the )LOAD command causes APL 
to automatically reopen that function and prompt the user to continue function 
definition or editing. (The user may choose to close the function immediately.) If 
)LOAD accesses a workspoce sealed by another user, the workspace is sealed, 
prohibiting any form of function editing or display. 



Examples: 

)LOAD KAWA 
KAWA SAVED 15:00 DEC 15 '84 

Loads workspace KAWA into the active workspace and prints a save report. Workspace 
KAWA was previously saved in the current user's account. 

)LOAD HENRY. .SECRET 
HENRY SAVED 15:08 DEC 15 '84 

Loads workspace HENRY into the active workspace and prints a save report. Workspace 
HENRY was previously saved with password SECRET in the current user's occount. 

)LOAD GRANOLA . TEST APL .PASSWRD 
GRANOLA SAVED 15:08 DEC 15 •8'i 

Loads workspace GRANOi.A into active workspace and prints a save report. Workspace 
GRANOI^ was previously saved with password PASSWRD in account TEST APL. 
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)NMS Displaying Global Names 



Syntax: 

)NMS [stringl [string2]] 



Parameters: 

stringl is any sequence of characters not including blanl< or carriage return. 
string2 is any sequence of characters not including blank or carriage return. 



Descr 1 pt 1 on: 

The )HHS command alphabetically lists the global names in the active workspace. 

Alphabetic ordering is illustrated in the examples. Note particularly the first )lfMS 

command since it indicotes where each name character lies in alphabetic order. 

If stringl Is specified all global names that are alphabetically equal to or greater 
then stringl are displayed. If stringl is not specified, all global names ore 
displayed. If a string includes more than 79 characters, those post the 79th ore 
ignored. Strings are only used for range demarcation in alphabetic ordering. If 
stringZ is specified, all global names that are alphabetically equal to or greater 
than stringl, and are also less than or equal to string2 are displayed. 



Examples: 
)NHS 

A.2 AO. 2 Al.2 AA.:^ B.Z 

)HMS AA 
AA.3 5.3 

)NMS Al AX 
Al.2 AA.2 



)OBSERVE Observing Intermediate Results 



Syntax: 
)OBSERVE 



Description: 

The )OBSERVE command observes intermediate results developed by APL as it interprets 
a statement. This could be thought of as a "super-trace" capability. Following an 
)OBSERVE command, the succeeding statement is observed along with any traced function 
lines that are encountered. Subsequent direct statements ore not observed unless the 
user precedes each of them by a new )OBSERVE command. Thus, an )OBSERVE command Is 
short-lived, applicable to only one direct statement. By setting trace-vectors for 
functions to be encountered during on execution, however, the user con observe 
arbitrarily selected statements until issuing another direct input line. 
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While an )OBSERVE command is in effect, CP-6 APL displays a series of observations. 
An observation consists of displaying: the current line being executed, a marker 
(error caret) beneath some character in that line, and the value resulting at that 
point in execution (empty results, as usual, cause no value to be displayed). The 
observation marker often marks the leftmost point reached, so far, during execution 
of the line; however, when a function yields its results, the marker is placed below 
the function for clarity. (The only exception is the Execute function in which case 
the "leftmost" rule appi ies. ) 



For "observed" lines, observations occur for: 

o Each operator result 
o Each function result 

o Arguments that have not already been observed on this line 
o Indexed arguments 

Observations are not made for ossignments since the assigned value has already been 
observed prior to the assignment. Observations are also not made for the full 
variable when it is used as on indexed variable; this eliminates lengthy displays in 
cases such as the following sample )OBSERVE command. 

A<-lOOOp'GORP' 
) OBSERVE 

B^A[5] This is the observed line. 

B-^Alb] 

A 

5 Observation of the argument 5. 

B^A15] 

A 

G Observation of the indexed argument >l[5]. 

Note in the above sample that A was not displayed. This is fortunate since its 
display would produce 1000 characters, most of which contribute nothing to the 
observe statement. 



Usage Notes: 

The ) OBSERVE command has three valuable uses: for debugging, for learning how a 
calculation is performed, and for developing better APL functions. Its value in 
debugging is obvious. Suppose a complicated APL statement produces a LENGTH ERR. By 
using the OBSERVE command and reissuing that statement, the programmer can view 
development of values leading up to the error and readily see what caused the 
probi em. 

The )OBSERVE command con be a tremendous timesaver. When presented with a new APL 
statement or function, the user can spend a great deal of time analyzing how it 
accomplishes its result. By observing a sample run, the interpretation path and 
values can be readily inspected, simplifying analysis greatly. The reader might 
apply this process to the following function. 

VPRIMESUPTO N;R;ItJ 
1 1] (A/(0»<(l+i?)o. U)v((i?<-ny*0.5)o.=/))/j4-H-/*iAr-17 

This function produces the prime numbers from 2 up to the positive integer specified 
as its argument. To observe this function, the user might proceed as follows: 



1 UTRACE 'PRIMESUPTO* Set to trace line 1 of the function 
)OBSERVE Request observations. 

PRIMESUPTO 15 Call the function. 

About 30 observations are made; then the 
)OBSERVE command "disappears". 



There are at least two ways in which the )OBSERVE command can be used to develop 
better APL functions. First, redundant calculations are mode obvious and the 
programmer con then eliminate such redundancies. The following function is an 
inefficient version of the PRIMESUPTO function. The user might try observing the 
function to discover how apparent such redundancies become under the )OBSERVE 
command . 
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7PRIHESUPT00 H 

[1] (A/(0»'(l + tl^*0.5)o. I (l*ty-l))v((lU*0.5)o. = (iAr-l)))/l + iAf-l7 



The PRIHESUPTOO function takes considerably more execution time (and produces more 
observations) than the PRIMESUPTO function shown previously. 

The fact that the )OBSERVE command is useful for developing better APL functions is 
not obvious. It depends on the creativity and imagination of the user. By viewing 
the manner in which a calculation is carried out. the creative user may recognize 
patterns that can be more easily produced by other calculations. In other words, 
observations con suggest alternate approaches to solving a given problem. 

One final note about the )OBSERVE command should be presented. Suppose the user 
suspends execution during an observed run by hitting the break key, for instance. 
This removes the )OBSERVE command. Subsequent execution will not be observed unless 
the user issues o fresh )OBSERVE. As stated earlier, this command is short— lived. 
(At times its short life con be inconvenient, but considering the voluminous output 
possible with the )OBSERVE command this is more often a convenience.) 



)OFF Logging Off 



Syntax: 
)OFF [HOLD] 



Parameters: 

HOLD requests APL to return to the calling run unit or IBEX. 



Description: 

The )OFF command discards the active workspace, exits APL, and logs the user off of 
CP— 6 (producing the CP-6 log off message). If HOLD is specified, the user is not 
logged off. NOTE: If APL has been called from a run unit, not directly from IBEX. 
)OFF HOLD returns to the calling run unit. 



Examples: 

)OFF 

CON=00:00:36 EX=00 : 00 : 00 . 36 SRV=00:00:01 :98 PMME=235 CHG=.44 
Logs the user off and displays the CP-6 log-off messages. 
)OFF HOLD 

f 

Ends APL communication and returns control to IBEX. 
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)OPR Communicating with Computer Center Operator 



Syntax: 
)OPR message 

Parameters: 

message is the actual message to the operator; it cannot exceed 254 characters. 
Note that the operator's console does not include special APL characters, so messages 
should be limited to ordinary alphanumeric characters. 



Descript ion: 

The )OPR command allows the user to send messages to the operator in the computer 
center and requests a reply. APL prints the word SENT and enters WAIT mode until the 
user presses the BREAK key or the operator response is received. 

Examples: 

)OPR CP-6 UP SUNDAY? 

SENT 

YES, FOR A WHILE. 

Illustrates sending message to the operator and receiving a reply. 

)OPRN Communicating with Computer Center Operator 

Syntax : 
)OPRN message 

Parameters: 

message is the actual message to the operator; it cannot exceed 254 characters. 
Note that the operator's console does not include special APL characters, so messages 
should be limited to ordinary alphanumeric characters. 



Descript ion: 

The )OPRN command allows the user to send messages to the computer operator, without 
waiting for a reply. APL responds to this command with the message SENT and then is 
ready for more input. 

Examples: 

)OPRN TRIAL MESSAGE. DON'T REPLY 

SENT 

Illustrates sending a message to the operator, with no reply expected. 
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)ORIGIN Setting Index Origin 



Syntax: 
)ORIGIN [n] 



Parameters: 

n is ei ther 0 or 1 . 



Descr i pt i on : 

The )ORIGItf command sets or displays the value of Q/O (index origin). There ore two 
index origins available, 0 and 1. The functions affected ore index of and index 
generator (t), indexing and axis operator ([]), grade up (i), grade down (t), and 
random number generation (?). 

The )ORIGIN command causes APL to set the index origin (the value of D/O) and to 
print a message indicating the previous index origin. If the user does not supply 
parameter n when issuing this command, the current index origin is displayed. Note 
that the )ORIGIN command affects the active workspace and is saved along with a 
workspace. The index origin can also be changed by assigning a value to the system 
variable QIO. 



Examples: 

)ORIGIN 

IS 1 

)ORIGIH 0 

WAS 1 

)ORIGIN 1 

WAS 0 



)PCOPY Copying from Saved Workspace 



Syntax: 

)PCOPY fid [list] 



Parameters: 

fid is a CP-6 file identifier of a saved workspace. 

list specifies a list of variable names, function names, or group names, 
separated by blanks. 



Descr ipt ion: 

The )PCOPY command, the Protected Copy command, is the some as the )COPY command 
except that a name is copied only if the name in the active workspace is undefined 
(see the )COPY command). 
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)QLOAD, )QCOPY, and )QPCOPY Quiet Commands 



Syntax: 

)QLOAD fid 
)QCOPY fid [I ist] 
)QPCOPY fid [list] 



Parameters: 

fid is a CP-6 file identifier of a saved workspace. 

list specifies a list of variable names, function names, or group names, 
separated by blanks. 



Descript ion: 

The )QLOAD, )QCOPY, and )QPCOPY commands are slight variants of the )LOAD, )COPY, and 
)PCOPY commands. The Q stands for quiet. The SAVED message normally shown at the 
conclusion of a load or copy is suppressed on a quiet load or copy. No other 
messages (i.e., error diagnostic) ore suppressed by the quiet commands. 

Certain APL application programs benefit from the quiet commands, programs that use 
execute-operations to load or copy without user intervention. The user is unaware 
that such )LOAD or )COPY commands ore executed, and would be puzzled by SAVED 
messages. 

The quiet commands should be inserted in programs only after the application Is well 
tested. In the event of an error subsequent to a quiet load or copy, it may be 
difficult to isolate the problem for lack of knowledge about the workspace 
env i ronment . 



)QUIT Leaving APL 



Syntax: 
)QUIT 



Descript ion: 

The )QUIT command causes the contents of the active workspace to be discarded, 

following which control is passed to the process that invoked APL (usually IBEX, the 

CP-6 Command Processor). The command is identical to the )END command. 
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)REPORT Selecting the Function Stop Display 



Syntax: 

)REPORT [FUNClTION]\LINE] 



Parameters: 

FUNCTION sets function stop display to function name and line number (default). 

LIHE sets function stop display to function name, line number and contents of the 
I ine. 



Descript ion: 

The )REPORT command is used to control the information displayed when a function stop 
occurs. The default display is the function name followed by the line number in 
brackets. Specifying the LINE parameter causes APL to also display the contents of 
the line at which execution stopped. 



Examples: 

)REPORT LINE 
WAS FUNCTION 

7FUN 
[11 1+1+2 
12] a COMMENT 
[31 V 

2 1 DSTOP 'FUN' 
FUN 

FUNll] 1+1+2 

)REPORT FUNCTION 
WAS LINE 

k 

FUN12] 

■*QLC 



)SALVAGE Copying from Saved Workspace 



Syntax: 

)SALVAGE fid [list] 



Parameters: 

fid is a CP— 6 file identifier of a saved workspace. 

list specifies a list of variable names, function names, or group names, 
separated by blanks. 
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Descri pt ion: 

The )SALVAGE command retrieves information from a workspace which the )LOAD or )COPY 
command report as broken. The process is identical to that performed for the )COPY 
command except that the current workspace must be CLEARed prior to issuing the 
)SALVAGE command, and any items In disrepair are not copied. 

If the file contents which describes the major structure of the workspace is 
defective, the )SALVAGE command will still be terminated with a broken workspace 
report . 



)SAVE Saving a Workspace 



Syntax: 
)SAVE [fid] 



Parameters: 

fid is a CP— 6 file identifier. Like other APL names, the workspace name can 
consist of one or more letters from a to z, or A to Z, or numbers. Unlike other APL 
names, o workspace name is limited to 31 characters. If omitted, the fid defaults to 
the current workspace name (set by the )WSID command). 



Description: 

The )SAVE command saves a copy of the octlve workspace. If the active workspace was 
loaded as a sealed workspace, the workspace cannot be saved by )SAVE or )COlfTINUE 
commands. Attempts to do so will result in a BAD FILE REF error. A word of caution 
is necessary about using passwords in the )SAVE command. If a saved workspace 
already exists with a given name and password, specifying the some name with a new 
password in the )SAVE command will not change the password. Instead it results in 
the error message BAD FILE REF. The previously passworded workspace must be deleted 
before a new version can be saved. To delete the old workspace, use the )DROP 
command with the name and password. The workspace is saved provided that file 
management write access is available to the current user for the fid (expressed or 
impi i ed) . 

When a workspace is saved while in the direct input mode (not in evaluated input, 
function definition, or execute modes), the variable QLX will be executed when that 
workspace is subsequently loaded. 

When a workspace is successfully saved, APL prints a save report giving the name of 
the workspace and the time end date of the save. The )SAVE command also updates the 
current workspace identification, i.e., WSID. The name of the saved workspace along 
with its password (if any) becomes the WSID for the active workspace. If the 
workspace connot be saved because it exceeds the available space in the user account, 
APL prints an error message. In this case, the user must delete some workspaces or 
other files from the account before saving any APL workspace. 

If a )SAVE command is issued during function definition mode, the currently open 
function is temporarily closed. The saved workspace carries an indication that the 
function should be reopened on )LOAD. After the )SAVE command, APL reopens the 
function and prompts the user to continue function definition or editing. 
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ExampI es: 

)SAVE GRAMOL A. .SECRET 
GRANOLA SAVED U:58 DEC 15 *8<t 

Saves a copy of the active workspace with specified workspace name and password, and 
produces a save report. 

)SAVE 

CONTINUE SAVED 14:59 DEC 15 

Saves o copy of the active workspace and produces a save report. 

)SAVE KAWA 
KAWA SAVED 15:00 TfC 15 '84 

Saves 0 copy of the active workspace named KAWA and produces a save report. 



)SEAL Saving a Sealed Workspace 



Syntax : 
)SEAL [fid] 



Parameters: 

fid is a CP-6 file identifier of the workspace to be sealed. 



Description: 

The )SEAL command is identical to the )SAVE command, but in addition the workspace is 
created with READ access to all accounts using APL as the execution vehicle. Thus, 
the user who creates the workspoce has unrestricted access to the it. All other 
users can only access the workspace with APL. If the save is not successful, BAD 
FILE REF, FILE SPACE TOO LOW, or other relevant error messages may be issued and the 
active workspace will not be sealed. 



)SET Changing Assignments of input/Output Streanns 



Syntax : 
)SET deb fid 



Description: 

Refer to the CP-6 Programmer Reference Manual (CE4e) for a complete description of 
the SET command in CP-6 IBEX. Any )SET command is passed to IBEX for processing with 
only a minor chonge to the DCS designation as noted below. 

The inclusion of the )SET command within APL permits error action by the user or, if 
error control is used, in APL functions. If any of the listed strings noted below 
are detected by APL, the corresponding substituted string is substituted before 
referral to IBEX: 
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STRING 



REPLACEMENT STRING 



INPUT 



#1 



OUTPUT 



#4 



D, D) B 



F$Qe. F$FQ1 



F$Q9 



User Prompts 

If either output or input is diverted from the terminal, the prompts normally issued 
to the user are omitted. On ASCII terminals with full duplex, the echoing of 
characters indicates that input is being accepted. The home device for on— line 
sessions is the terminal. In batch the home devices are the command stream (card 
reader) for input, and line printer for output. 



Echoing of Input 

If input is coming from somewhere other than the user's terminal, then APL input (but 

not blind-input) is echoed to the output setting depending upon the IBEX ECHO 

setting. If input is echoing end this is not desired then the APL command: 

)ID0NT ECHO 

should be issued. Conversely, echoing may be initiated by the APL command. 
) I EC HO 



Errors on Input or Output 

If normal input or output is reassigned from the home device by the )SET command and 
an I/O error occurs, the input (or output) setting is returned to the home device(s). 
This is the user's terminal for on— line users, the card reader and line printer for 
batch. If error control is not in effect, an I/O error message is then output. If 
control is In effect for I/O errors, no error message is output. The user's error 
control function should note that input and output have been restored 'home' from 
their )SET command assignments. 



Break Response 

If normal input or output is reassigned from the home device by a )SET command, it is 
restored to the home device by a break. If the user has taken break control, the 
function which manages break control should note that input and output have been 
restored to the home device and terminal. 



)SI Controlling the State Indicator 



Syntax: 



)SI 10N\0FF\CLEAIR]] 
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Parameters: 



CLEAIR] removes every entry in the stote indicator. This may free a substantial 
amount of workspace and is a valuable tool for recovering from WS FULL errors. 

ON suspends the executing function if an error occurs (the default). This is 
useful when debugging the workspace since it allows access to local variables for the 
suspended function. Suspending the function, however, expends a certain amount of 
the active workspace, and this can be a disadvantage. The ON option sets state 
indicator control for errors that may occur during subsequent execution of functions 
in the active workspace. 

OFF sets state indicator control to avoid suspending a function when an error 
occurs. Note that the OFF setting applies only to errors. It has no influence over 
execution breaks or stop vectors; these may still cause function suspension. The OFF 
option sets state indicator control for errors that may occur during subsequent 
execution of functions in the active workspace. 



Description: 

The )SI command displays the contents of the state indicator, which is a list of 
suspended and pendent functions. For a discussion of the state indicators and 
suspended and pendent functions, see State Indicators in Section 7. 



ExampI es: 

)SI 
A[2] * 

;irr[5j 

5[31 * 

The most recently suspended function is listed first. An asterisk after an entry 
indicates a suspended function; no asterisk indicates a function that is pendent. In 
the above example, function A has been suspended just before line number 2, and 
function B just before line number 3. Function XY is pendent because it referenced 
function A at line number 5. If )SI is issued when evaluated input is pending, the 
input request will also be displayed, using the □ character. If the )SI command is 
issued when on 'execute' is pending, the execute state will be indicated, using the £ 
character . 

Errors causing suspended function should be corrected as soon as possible. Suspended 
functions can be cleared from the state indicator with the branch arrow (■►). 
(Remember that the state indicator with its list of suspended and pendent functions 
and local variables may take up a lot of workspace.) Each branch arrow clears the 
most recent suspended function and all pendent functions associated with it. This 
can be repeated until all suspended and pendent functions have been cleared; that is, 
until the )SI command returns a blank line. Applied to the above example, this would 
g i ve 

)SI 
B13] * 

)SI 

A more convenient method for clearing the state indicator is to issue the following 
command : 

)SIC 

To restore normal state indicator control, the command 
)SI ON 

may be issued. This setting also occurs automatically if a )CLEAR command is issued. 
The ON or OFF state indicator control is saved when the active workspace is saved, 
and loaded when the workspace is loaded. Copying does not alter the control of the 
active workspace. 
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)SIC Clearing the State Indicator 



Syntax : 
)SIC 



Descr ipt ion: 

The )SIC command removes every entry in the state indicator. This may free a 
substantial amount of workspace and is a valuable tool for recovering from WS FULL 
errors. 



)SIL Listing the State Indicator Lines 



Syntax: 
)SIL 



Descript ion: 

The )SIL command lists the same information as the )SI command and also lists the 
contents of the lines that ore currently in execution. For pendent functions, it 
indicates the position within each line at which execution is to be resumed. An • in 
column 1 indicates a direct input line in execution. 



Examples: 

)SIL 

AlZ] CC*-l 20 BB 

A 

* XY 

A 

B13] VAL^iPAYitlOO)/PAY 0 PAY*UFREAD 1 20 

* B 

A 



)SINL Listing the State Indicator 



Syntax: 

)SIlfL 10N\0FF\CLEA[R]] 



Parameters : 

CLEAIR] removes every entry in the state indicator. This may free a substantial 
amount of workspace and is a valuable tool for recovering from WS FULL errors. 

ON suspends the executing function if on error occurs (the default). This is 
useful when debugging the workspace since it allows access to local variables for the 
suspended function. Suspending the function, however, expends a certain amount of 
the active workspace, and this can be a disadvantage. The ON option sets state 
indicator control for errors that may occur during subsequent execution of functions 
in the active workspace. 
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OFF sets state indicator control to ovoid suspending a function when an error 
occurs. Note that the OFF setting applies only to errors. It has no influence over 
execution breaks or stop vectors; these may still cause function suspension. The OFF 
option sets state indicator control for errors that may occur during subsequent 
execution of functions in the active workspace. 

Description: 

The )SINL command lists the same information as the )SI command and additionally 
lists the local variable names appearing in the suspended and pendent functions. For 
a discussion of the state indicators and suspended and pendent functions, see State 
Indicators in Section 7. 



ExampI es: 

)SIHL 

A[Z\ * BB CC DD 
XY15] 

B13] * PAY VAL 

where BB, CC , and DD are local variables appearing in function A; and PAY and VAL are 
local variables appearing in function B. 

Errors causing suspended function should be corrected as soon as possible. Suspended 
functions can be cleared from the state indicator with the branch orrow (*) . 
(Remember that the state indicator with its list of suspended and pendent functions 
and local variables may take up a lot of workspace.) Each branch arrow clears the 
most recently suspended function and all pendent functions associated with it. This 
can be repeated until all suspended and pendent functions have been cleared; that is, 
until the )SI command returns a blank line. Applied to the above example, this would 
give: 

)SIHL 

fit 31 * PAY VAL 

■* 

)SI 



)STEP Single Step Execution 



Syntax : 

)STEP ILINEIFUNCTION] [n] 



Parameters: 

n indicates the number of statements to step. This can be any integer from 1 to 
99999. 

LINE specifies to stop before the next APL line is executed within any function. 

FUHCTION specifies to stop before the next line is executed within the current 
f unct ion. 
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Description: 

The )STEP command executes the line at the top of the state indicator and stops 
before another function line is executed. That is in the simplest case where the 
current line does not coll another user function, the line will be executed and 
execution will halt before executing the next line. A single right bracket and a 
carriage return on a line also has this effect. 



Ex amp I es : 

)STEP LI HE 
FUH I 

FUHll] 

)STEP 

FUH12] 

)STEP 
FUH211] 

)STEP 

FUHll] 

)STEP 

FUH12] 

)STEP FUNCTION 

FUNll] 



)TERMINAL Specifying Input/Output Device 



Syntax: 

)TERMINAL I INPUT \ OUTPUT] [n] 



Parameters: 

INPUT specifies that only the input translation tables are to be affected. 

OUTPUT specifies that only the output translation process is to be affected. 

n indicates the device to be assumed by APL end can be any of the values 1, 2. 3, 
4, 5, 13, 14. 



Descr i pt i on : 

The )TERMINAL command is used to identify to APL the input/output device being used. 
This command is not normally needed for users operating on a terminal or submitting 
batch runs for card input and line printer output. New terminal declarations ore 
acceptable at any time during an APL session, but the user should be aware of the 
consequences (such as error message discrepancies and input/output translation 
problems). UTT also results in the integer n; this may be useful for APL programs 
that are sensitive to terminal type. Using )TERMINAL INPUT or )TERMINAL OUTPUT 
modifies only the specified (input or output) translation table. This form is useful 
when APL input or output is diverted to an alternate device by the )SET command. 

CP— 6 supports two types of input/output devices with respect to APL sessions: 

o Those capable of printing the APL character set. 

o Those capable of printing the ASCII— 96 character set. 

Specifying a terminal of type 1, 13. or 14 indicates the APL character set; types 2, 
3, 4, or 5 specify the ASCII set with types 4 and 5. representing underscored letters 
as lowercase letters. Types 2 and 3 represent underscored letters as the mnemonic 
combination $U followed by the letter. For types 3 and 5, certain characters (0, 1, 
^1 ^, / and \) are represented via appropriate backspace overstrike combinations. 
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Examples: 

)T£RH 5 

WAS 1 

Indicates that a Diablo 1620 terminal (or equivalent) with a non-APL daisy wheel is 
being used. 

)TERH 

IS 5 

Shows that the non-APL Diablo 1620 terminal was most recently declared. 
)TERH OUTPUT k 

WAS 5 

Sets output translation for the line printer, but does not change input translation. 

APL recognizes three separate choices for input/output character translation. 

Input terminal type is chonged by either )TERM INPUT n or )TERH n. Output terminal 
type is changed by either )TERH OUTPUT n or )TERM n. 



Usage Notes: 

The combination of the )TERMINAL and )SET commands permits a variety of I/O 
operotions with devices and files. The user should be warned that some choices, 
particularly changes to the home terminal, can result in difficulties carrying on 
further terminal communications. In general, )TERH OUTPUT k should be used for line 
printer output. Output which is filed and reread by the same user should preferably 
use home terminal type. If several users with different terminals want to access the 
file. 0 common type should be agreed on, probably 1 for APL or 4 for ASCII. 



)VARS Listing Global Variable Names 



Syntax: 

)VARS [stringi [string2]] 



Parameters: 

stringi is any sequence of characters not including blank or carriage return. If 

stringi includes more than 79 characters, those past the 79th are ignored. 

string2 is any sequence of characters not including blank or carriage return. 



Descr ipt ion: 

The )VARS command alphabetically lists the names of global variables in the active 
workspace. Strings are used only for range demarcation in alphabetic ordering. If 
stringi is not specified, all global variable names are displayed. If string2 is 
specified, global variable names that are alphabetically equal to or greater than 
stringi and are also less than or equal to string2 are displayed. Alphabetic 
ordering is illustrated in the example. Note particularly the first )VARS command 
since it indicates where each name lies in alphabetic order. 
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Examples: 

)VARS 

A AO Al AA AB ABC AA AL B 

)VARS AA 
AA AB ABC AA AL AL B 

)VARS A AA 
A AO Al AA 

)VARS AAA AB 

AB 

)VARS ABC ABC 

ABC 

)VARS A Z 

A AO Ai AA AB ABC AA AL AL B 



)WIDTH Setting Line Width 



Syntax: 
)WIDTH [n] 



Parameters: 

n is an integer number ranging from 32 to 390. 



Descr ipt ion: 

The )VIDTH command changes or displays the value of UPW (Platen Width). This system 
variable is used to indicate the length of the longest line that APL will output. In 
a clear workspace the platen width defaults to the platen width when APL was 
initially invoked, or the closest value acceptable by APL to the initial value. The 
value of UPV is saved with a workspace and is restored when a workspace is loaded. 



Examples: 

)WIDTH 

IS 120 

Displays the current width of a line output (i.e., 120 printing positions). 

)WIDTH 50 
WAS 120 

Changes the width of an output line to 50 print positions. The previous line width 
setting was 120. 



8-42 



)WIDTH Setting Line Width 



CE38-04 



)WSID Identifying the Active Workspace 



Syntax: 
)WSID [fid] 

Parameters: 

fid is the new CP-6 file identifier of the active workspace. If fid is not 
specified, the fid of the active workspace is displayed. APL responds with a message 
showing the previous workspace name. This name con be from 1 to 31 characters. 

password a password may be specified, but a previous password is never displayed. 

Descript ion: 

The )WSID command allows the user to identify the active workspace or to change its 
name. The )WSID command cannot be used to change the name of a sealed workspace. 

Examp I es : 

yvsiD 

IS JOKES 

Lists the name (JONES) of the active workspace. 

)WSID 

IS GOSTYLE,ZZZ02MAR 

Lists the name GOSTYLE and account ZZZ02MAR of active workspace. 

yusiD SMITH 
WAS GOSTYLE. ZZZOZMAR 

Changes the name of the active workspace from GOSTYLE to SMITH. 
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Section 9 

Report Formatting 



CP-6 APL provides a formatted output capability with the system function UFHT in 
addition to the » function. UFHT utilizes a set of format control phrases that are 
applied to a list of APL expressions. Each APL expression may evaluate to numeric or 
character scalars, vectors, or matrixes. The format control phrases, called format 
specifications, are described in Table 9-1. 



Format Specifications 

UFHT recognizes twelve data format codes. Each code is described in the following 
table. 



Table 9-1. Format Specifications 


Code 


Descr i pt i on 


A 


Alphanumeric specification. 


E 


Floating-point with exponent (scientific format). 


F 


Floating-point to fixed decimal position. 


I 


Decimal integer. 


X 


Blank insertion. 


T 


Column Tabbing. 


G 


Picture formatting. 


D TEXT D 


Text insertion. 


0 TEXT 0 


Text insertion. 


< TEXT > 


Text insertion. 


c TEXT 3 


Text insertion. 


" TEXT " 


Text insertion. 



Format specifications may be in any of the following forms: 

[r] 4w 

[r1 £w.s 

[r] [q] fw.d 

[r] [q] /w 

[r] ^w 

[r] D TEXT d 

r c 
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[r] [q] G D TEXT D 
where 

r is an optional unsigned integer constant indicating the specification is to be 
repeated r times. When r is omitted, it is token as 1. 

w is an integer constant indicating the total field width, or number of print 
positions occupied by the formatted value (or blanks, for X type). 

s is an integer constant indicating the number of significant digits to be printed 
in £■ format; s must be less than w— 5. 

q is on optional "qualifier" or "affixture" code used to position and affix 
characters to the results of / and F output forms. The available codes and their 
uses ore described later in this section. 

d is an integer constant indicating the number of digits to the right of the 
decimal point in F formats; d must be less than w. 

c is the column number at which the next field will start to be formatted. 



Format Specifications versus Data Types 

Format A may be applied to character data only. Formats E, F, and / may be applied 
to numeric data only. 

Arrays with rank above 2 (matrix) cannot be processed. If a value cannot 
meaningfully be expressed in the format end field width specified, the field is 
filled with asterisks. 



Format Statement (Left Argument) 

A format statement is the left argument of UFMT, operating on data values in the 
right argument. The format statement consists of a character vector mode up of one 
or more format specifications separated by commas. The left argument of UFMT must 
always be a valid format statement. For example, 

'3/3,2f8.2,Jiri2,/3' UFMT ... 
Parenthesis may be used with repeat counts around phrases. For example: 

•/5,3(;2,/'8.2)' UFMT ... 
Parenthesis may be nested up to 7 deep within format phrases. 



Format Data List (Right Argument) 

The right argument of UFMT must be a list of APL variables or expressions, separated 
by semicolons. The expression may represent scalars. vectors, or arrays. For 
example, 

... UFMT (VARIABLEl;YARIABLEl*VARIABLEZi'SUMn 

If the list contains only one value, the parentheses may be omitted. The value of 
each expression must be simple and all numeric or all character. 
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Operation of UFMT 



UPMT uses the format specifications in its left argument (the format statement) to 
control printing of its data list (right argument) on one or more columns. The 
syntax is 

'format stmt' UFHT expr 

or 

•format stmt ' UFHT I ist 

The result of executing UFHT is one or more "lines" of formatted character data. A 
line may be as long as workspace allows. In printing, long lines are broken up 
according to the UPW setting. If more than one line is produced (as will be the case 
if the data list includes vectors or arrays with more than one row) all lines ore of 
the some length. The result, then, is a character matrix. 

If QFMT is not used within a larger expression, the amount of temporary workspace 
required is only the length of one line. Thus, formatted output may be used to 
process output that would overflow available workspace if assigned or used in its 
entirety. If UFHT is used within a larger expression, the result is always a matrix, 
even if only one line, and space for the full matrix is required. The operation of 
UFHT on various right arguments is described below. 



Formatting Scalsu" Arguments 



If the data list consists exclusively of scalers, a single line is created. Format 
specifications ore used in turn to process elements of the data list in left to right 
order. Blank insertion and text insertion specifications do not "use up" elements of 
the data list, however. A repetition indicator causes a particular specification to 
be applied the designated number of times to successive elements of the data list. 
If there ore fewer format specifications (counting repetition indicators) than values 
to be formatted, the list of format specifications is reused as necessary until the 
data list is exhausted. 



Examples: 

•/3,>l5,;ir5' UFMT (100;'i1' ;200;'S') 
100 A 200 B 

'5F5.2' UFHT (1;10;100;"10;"1) 
1 .OOlO.OO********-**"! .00 

This lost example illustrates the use of the repetition indicator. Also note the 
asterisks indicating that the value 100 and ~10 would not fit in the specified 
format. 



Formatting Vector Arguments 

If the data list includes vector and scalar arguments (or vectors only), the number 
of lines generated equals the length of the vector with the most elements. Each 
vector creates a "column" in the resulting character array. The columns of shorter 
vectors or scalers ore extended by blanks. 
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Examples: 



3.1 .123 "l.23'» 5678 



3.100£0 
1.230jr"l 

"i.23*ro 

5.6781:3 



2 
3 



•2/5,il2»D/'Wr 

10 A 

11 B 



(12 3 *;10.* lO.ei^ABCDEFn 



C 
D 
E 
F 



In the last example, note the rounding off of values as required for I format 
specifications, and also note the different column lengths. 



Formatting a Vector on One Line 

The normal result for UFMT on vector arguments is columnar formatting, but it is 
often desirable to create a formatted row for vectors. There are two ways this can 
be done: 

o Ravel the result of UFHT . This method is appropriate if the result contains a 
single column. 



,*AZ' UFMT » DOUBLE SPACE • 
DOUBLE SPACE 

0 1 lii UO IkOO 

o Reshape the vector as a 1 by N matrix. (This method uses a property of the 
operation of UFMT on matrixes, as discussed below.) 

V^'TRIPLE^SPACE' 
'A3' UFMT (l,pV)p V 
T R IPLE*- SPACE 



Formatting Matrix Argunnents 

If the data list includes a matrix argument, each column of the matrix occupies a 
column in the formatted output. Each row of the matrix creates an entry on a "line" 
of output. Note that a 1 by N matrix creates a single row, and an N by 1 matrix 
creates the same output form as an N element vector. 

In essence, QFMT outputs matrixes in the same shape as unformatted output would, but 
permits control of decimal placement, column positioning, etc. 



Examples: 

IOTA-*-Z 5pil5 
•fS.PDfWr IOTA 
1.0 2.0 3.0 4.0 5.0 
6.0 7.0 8.0 9.0 10.0 
11.0 12.0 13.0 1<^.0 15.0 



ExampI es: 
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JKL^'JKL' 

VECT*-l 2 3 4 

HATt-2 2p.l 2.0 30 ~k 

*Al,F6.3,I5,2F6A' UFHT UKLiPI iVECT ;HAT) 
J 3. HO 1 0.1 2.0 
K 2 30.0 "4.0 

L 3 
4 



Picture Format 



Picture formatting provides the greatest control over the result of numeric 
formatting. The syntax of a picture format is: 

[r] [g] G D TEXT D 

The B, C, L and Z format qualifiers ore not permitted with picture formatting. The 
text field may contain any text. The two characters, '9' and 'Z' by default control 
the formatting of the numeric data. The data may be scaled by K qualifiers and then 
rounded to integer for formatting. 

A '9' in the text field selects the corresponding digit from the data. A in the 
text field selects the corresponding digit from the data only if the digit is not a 
leading or trailing zero. 

As the text is scanned, characters other than 9 or Z are copied to the result. If 
there are leading or trailing Z controls, non-special characters are copied into the 
result only if the last Z selected a digit. 



Examples: 

*K2G<ZZZ,ZZZ DOLLARS, ZZ CENTS>' QFMT 31415.962 
31.415 DOLLARS, 96 CENTS 

'CD99/99/99D' DFMT 52282 
05/22/82 



Forms of Output Values 

The following rules determine spacing and content of output fields for various format 
specifications. 

o Right— j ust i f icat ion. For A, I, and F specifications, the value is 

right-justified in the field and preceded by blanks where appropriate to fill out 
the field. 

o E format. The letter £* always occupied the fourth space from the right in the 
field. Three spaces ore reserved for the exponent value and exponent sign. If 
less than three spaces are needed, the right-most space or spaces are blank. In 
this format, there is columnar alignment of the decimal points and letter E. 

o □ TEXT □ format. Characters between the quote-quods (or other text insertion 
format specifications) are inserted directly into the output line. There are as 
many insertions as there are lines of output. No data list elements are expended 
by text insertion. 

o Significance of results. The value of UPP is ignored in QFMT output; a maximum 
of 20 significant positions ore displayed, however. If a format specification 
requests more than 20 significant digits, digits beyond the eighteenth, and to 
the left of the decimal point are replaced by zeroes. Excess digits to the right 
of the decimal point ore replaced by blanks. 

o Field width. If field widths ore too small to hold formatted values according to 
the specification, the fields are filled with asterisks. 
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Format Qualifier and Affixture Codes 

/ and F format specifications may be immediately preceded by one or more qualifier or 
affixture codes. 

o Quel if ier codes 

B Leaves the field blank if the result would otherwise be zero. 

C Inserts commas between triads of digits in the integer part of the result. 

L Left— just i f ies the value in the result field. 

Z Fills unused leading positions in the result with zeros (and commas if C is 
also used) instead of blanks. 

Kr\ Scaling factor. Before formatting, the data is multiplied by the power of 10 
indicated by n. n may be any positive or negative integer. 

o Affixture codes 

M< TEXT > prefixes negative results with the text instead of the negative sign. 
^< TEXT > postfixes negative results with the text. 
P< TEXT > prefixes positive results with the text. 
0< TEXT > postfixes positive results with the text. 

R< TEXT > presets the field to the text, which is used as many times as 

necessary to fill the field. The text is replaced in parts of the 
field filled by the result. 

S< TEXT > symbol substitution. 

Note: If B and R are both specified. R overrides B. 

Qualifier and affixture codes do not extend field widths. The modified result 
must fit in the field width specified or asterisks will be substituted. 

H and Q affixtures, since they postfix the text, shift results to the left by the 
number of characters to be postfixed. 

Examp I es : 

V^lZe 0 ".25 ~6k ■123'j5.67 

•s/'io. i,ji:2,s;8,jir2,c;io,;i:2,z,f9' ufmt (ViV'.ViV) 

128.0 128 128 128 

0 0 

"0.3 0 0 

"12345.7 "12346 "12,346 "12346 

•2'fl0.2,A:2,MIl*'*Cl/'10.1,Ji:2,P<+>/8' UFMT 
0000128.00 128.0 -t-iaS 

0000000.00 0.0 4-0 

"000000.25 **0.3 +0 

"000064.00 **64.0 "64 

"012345.67 **12345.7 "12346 

»c<f-i-+>/g,jr2,fl<*>;8» Ufmt iv-.v) 

128+-I-+ *****128 

0+-I-+ *******0 

0+++ *******-0 
"64 *****"64 
"12346 **"12346 

Combinations of qualifier and affixture may be used together to provide various 
output forms as shown below. 
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UZ,2h5.61 ~$9.98 



Format Symbol Substitution 

UFMT uses predefined characters in formatting output and interpreting specifications. 
In some cases, the default characters may not be appropriate. The 5 qualifier allows 
these defaults to be changed. The default symbols and their applicable format 
phrases are listed in the following table. 



Table 9-2. Default Formatting Symbols 


SYMBOL 


USES 


PHRASE 


9 


digit select 


G 


Z 


zero suppress digit select 


G 


* 


field overflow 


FGI 


0 


Z qualifier fill/lead zero fill 


FGI 




non-significant digit 


FGI 




C qualifier character 


FI 




decimal point 


F 



The default character con be replaced by first specifying the default character 
followed by the character to be used in its place. 



ExampI es : 

) •S<. , , .>Cn6.2' UFMT 2718235. 419 

2.718.235,49 



Format Result 



The principal use of UFMT is to provide lines of formatted output. However, if UFMT 
is used as part of a larger APL expression, the result of executing UFMT is a 
character matrix which may be manipulated and used just as any other character 
matrix. 



Format Error Reports 



If the right argument includes an array of higher order than matrix, or the left 
argument is not a vector, a RAMK ERR results. 

If the left argument is not simple and all character data, and contains no format 
specifications, or contains a format specification with inconsistent parameters (such 
as d greater than w, or w « 0), a DOMAIN ERR results. 

If there is incorrect syntax in the right argument, o SYNTAX ERR results. If there 
is incorrect syntax in the left argument, a FORMAT SYNTAX ERR results. 

If the line length of the result is too big for the remaining workspace, or UFMT is 
included in a larger expression and the total result exceeds the remaining workspace, 
VS FULL results. 
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Formatting Aids 



In addition to UFMT , the following system functions may be used to aid in output 
formatting. The )SET and )TERMINAL commands, described in Section 8, may also be 
used in the overall process of output report generation. 



UPGE Function (Skip to New Output Page) 



Syntax: 

UPGE 

Descr i pt i on : 

UPGE is a ni Iodic function with an empty vector result. When executed, if output is 
to a printing device, the current page will be ejected. If output is to a unit 
record type device and UHDR has been established by the )SET command, a standard 
header line will also be produced. 



UNLS Function (Number of Lines Remaining) 

Syntax: 
Parameters: 

/ is a simple integer scalar. 
Descri pt ion: 

QiLS is a ni iodic function with on integer result. If output is to a device with 
line count applicable, the result is the number of lines remaining to print on the 
current output page. If not, the result is zero. 



UHDR Function (Set Page Heading) 



Syntax: 

OHDR T 
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Parameters : 

T ISO simple character scalar or vector of maximum length 160. 
Description: 

This function establishes the output header line which will be displayed at the start 
of each page if output is set to a printing device. This system function uses a CP-6 
facility which does not recognize special APL characters. If special characters or 
overstrikes are included. UHDR may not produce correct headings. 

Possible errors: 

A DOMAIN ERR is reported if: 

o r is not text or simple. 

A RANK ERR is reported if: 

o r is not a scalar or vector. 

A LENGTH ERR is reported if: 

o T contains more than 160 items. 

UVFC Function (Set Line Spacing) 



Syntax: 

UVFC C 



Parameters: 

C is a simple character scalar or one-item vector. 



Descr i pt ion: 

UVFC is a monadic function with empty vector result. The right orgument must be a 

single character. When UVFC is executed, the character in the right argument becomes 

the vertical format control character for the next print line. After that line is 

printed, the default character is restored as the vertical format control character. 

Refer to the CP-6 Programmer Reference Manual (CE40} for the specific values of 
vertical format codes. 
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UXL Function (Translate Text) 



Syntax: 

R^A UXL B 



Parameters: 

A is a simple character vector of length less than 513 (unspecified character 
positions are treated as blanks). 

B is a simple character array. 

R is the translated result with the same shape as B. 



Descr ipt ion: 

The UXL function facilitates special character set translations within APL. The 
result of the UXL function has the some shape as the right argument and consists of a 
translation of the right argument. The index position in 0^4^ of each item of the 
right argument is used to index the left argument to obtain the corresponding result 
item. The result is exactly equivalent to: 

{5l3*A)lUAVt B] 

but requires much less workspace. 

This feature is designed to overcome problems encountered in character set 
differences between various devices. It allows any character mapping, including 
mapping several characters to the same result character. An example of this use 
might be to map all 'illegal' characters to some unique character. Another example 
is as fol lows: 

/.<-"H-i256 
Z,(97+t26]<-64 + i.26 
Lf-UAVIUIO+L] 

This value of L, used as left argument of UXL, converts lowercase letters in the 
right argument to similar uppercase letters in the result. 



Possible errors: 

A RAtfK ERR is reported if: 

o AT is not a vector. 

A LENGTH ERR is reported if: 

o X contains more than 512 items. 

A DOMAIN ERR is reported if: 

0 any item of X is not a scalar character. 

A DOMAIN ERR is reported if: 

o the right argument T contains an item which is not a scalar character. 
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Section 10 
Execution Stops 



Execution is stopped if any of the following conditions occurs: 

1. Execution is completed (a normal stop). 

2. Execution break occurs (BREAK key is pressed), and sidetracking does not occur. 

3. User input is required (quad or quote-quad input). 

4. Stop control line is encountered. 

5. Error is encountered, and sidetracking does not occur. 



Normal Stop 

Execution comes to o normal stop ofter any action indicated by direct input is 
completed. It should be noted, however, that a direct input prompt does not 
necessarily mean that all pending execution is completed. The user can determine 
whether any execution is pending via the )SI command. 



Execution Break 



An execution break (that is, the BREAK key) con be issued by the user at any time. 
There may be a short delay until output stops. Sidetracking can be used to gain 
break control within on APL function; in this cose execution does not stop, but is 
"diverted" (see Sidetracking on Errors and Breaks). 

Either a soft break or interrupt may be signalled by pressing the BREAK key. The 
first break during the execution of a line of APL is a soft break. Execution of the 
current line continues until the end of the line is reached at which time, the 
currently executing defined function will suspend. If a second break is sent before 
the soft break is processed, this signals a hard break or interrupt and the currently 
executing line is removed from execution. An INTERRUPT message is displayed along 
with the line that was in execution and a caret indicating the position in the line 
that execution was interrupted. In this case, if the APL line contains "side 
effects" such as embedded assignments or shared variable accesses, then the line may 
not be easily restortoble. 

APL's reaction to break also depends on whether the BREAK key is pressed during 
execution mode or definition mode. If break is used during (non— f unct i on) execution, 
APL stops any output in progress and skips to the next line and indents six spaces to 
prompt for new input. If breok is used during execution of a defined function, APL 
displays the function name and the line number being executed. 

If break is used during display of a function. APL wi M exit from function definition 
mode if a closing del was included in the display command. If the display command 
did not have a closing del, APL will remain in function definition mode and will 
prompt with the next line number after the line range being displayed. 

Execution breaks are usually not allowed to interrupt the execution of a system 
command. However, those that produce lengthy display can be stopped: )FNS, )GRPS, 
)LIB, )SI, )SIlfL, and )VARS. Break is also used to abort the wait resulting from the 
)OPR system command. 
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stop For User Input 



Execution may be stopped by an input request in a line. The normal response to a 
quad or quote— quad input request is a line of input. While quad input is pending, 
BREAKS are treated as normal execution errors and thus cause the quad input request 
to be re-issued. If the user's program contains a loop such that the user is 
repeatedly prompted for input, the user may escape as follows: 

1. For quad input, type o branch arrow (-»} followed by a RETURN. An example is 
shown below: 

V PITIHES 
[1] OD 
[21 *1 

7 

P [TIMES 

U'. 

I 

3. 141592654 
"1 

"3.141592654 
)SI 

□ 

PITIHESl 1 1 
□ : 

)SI 

In this example the user has defined a function, PITIMES, that repeatedly 
requests input and provides a result. The first )SI command shows that an input 
request and line 1 of PITIMES are pendent. After the the input request is no 
longer repeated. The second )SI command shows that the loop has been broken and 
PITIMES is no longer in use. 

2. For quote-quad input, press the BREAK key twice to cause an INTERRUPT at the 
point of the quote quad input request. 



Stop Control Vector 

As described in Section 7 (under Suspending Execution), a stop control vector can be 
used to specify the exact place a function suspension is to occur. The user can set 
a stop control vector by executing the USTOP system function with the function name 
enclosed in quotes as the right argument and the line numbers at which the function 
is to be suspended as the left argument. For example, suppose the user wants to 
suspend execution of function HH at lines 2 and 4; by typing the expression 

2 4 QSTOP 'HH' 

APL will then suspend function execution just before each specified line number is 
executed, print the function name and line number, skip to the next line and indent 
six spaces to prompt for user input. (See the possible effects of 05^ described in 
Section 11.) 

HH 

HH12] 

The user may then operate as desired, in direct input mode with the function 
suspended, and can resume or terminate function execution at any time. Function 
execution can be resumed by appropriate branching; for example, an entry of *2 will 
resume execution of the suspended function at statement 3. Termination can be 
accomplished by a branch to a non-existent line number (-^0 is a convenient choice). 
The function suspension can also be abandoned by a suspension clear statement, which 
is a branch arrow without any line number. 
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A stop control vector can be specified during execution mode, or during function 
execution as one of the statements of a defined function. To discontinue an active 
stop control vector, assign on empty vector to that stop control vector; for example, 
"USTOP 'HH' will turn off the stop control for function HH. 



Error Stop 

As soon as APL detects on error in o statement, execution of that statement is 
terminated and any partial result is lost, except for assignments that were completed 
before the error was detected. Unless sidetracking occurs. APL prints a message 
indicating the type of error, displays the erroneous statement with a caret below the 
place the error was detected, (see also the discussion of error messages for the 
Execute operator in Section 5), and prompts for input. (See the possible effects of 
USA described in Section 11.) The user con then correct the statement. An example 
of error detection is shown here: 

DOMAIN ERR 

A . 

If 0 statement contains more than one error, only the first (rightmost) one detected 
by APL will result in on error report. The next error will not be detected until the 
user has corrected the first error, as illustrated here: 

DOHAIU ERR 

J:1<-(4^-0)x(2-5-0) 

A 

;i:i*{ii-o)x(2-5-i) 

DOMAIN ERR 

A 

If on error is detected in a statement with multiple specifications, any assignments 
to the right of the error will be completed, as illustrated here: 

DOMAIN ERR 

A 

B 

5 

C 

0 

During function definition some types of errors are detected immediately while other 
types ore not detected until later when the function is executed. Definition errors, 
and character errors are detected immediately and must be corrected as soon as an 
error report is printed. 

VR^B TRI H 
[11 AREA^0.5*B*H 
[21 DIAGONAL^(iHi^2)B*2)*0.5 
[31 R^ ARE A iD I AGONAL 

[41 [0.5 ri?/ CALCULATES AREA AND DIAGONAL OF TRIANGLE 
DEFN ERR a 

[0.51 fl TRI CALCULATES AREA AND DIAGONAL OF TRIANGLE 
[0.61 7 

Linescan errors are detected immediately and may be corrected immediately by function 
editing or its correction may be deferred. All other errors in a defined function 
are detected when the function is executed. When APL encounters each error during 
function execution, it suspends execution and prints an error report containing the 
type of error and the function name and offending line and statement (with a caret 
marking the place the error was detected). For example, the following error message 
is produced because a Not function had been entered instead of a multiplication sign: 
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5 TR! 8 
SYNTAX ERR 

A 

An error that causes suspended execution can be corrected during the suspension or 
after termination of execution. 

1. To correct an error during suspended execution, the user can follow normal 
function editing procedures (see Section 7). For example, 

SYNTAX ERR 

TRn3] DIAG0NAL^(iH*2)~B*Z)*0.5 

A 

VTRnZ] DIAGOHAL^HH*Z ) *B*2 )*0 . 57 

After correcting an error, the user con resume execution at the line suspended by 
specifying a branch to that line number. Thus, the expression -^3 will resume 
execution at line 3 (starting at the right, as usual for APL) . 

2. To correct on error with termination of execution, the user enters a branch arrow 
to terminate function execution, edits the function as necessary, and then 
reexecutes the function. For example: 

SYNTAX ERR 

TRl[Z] DIAGONAL*-{iH*2)'-B1cZ)1c0.5 

A 

^TRI[3] DIAGONAL*-^ (H*Z ) *B*Z )*0 . 57 

5 TRI 8 

Each branch arrow removes the most recent suspension from the state indicator 
list. Thus if several suspensions hove occurred since the last suspension clear, 
more than one branch arrow (suspension clear) will be required to clear the state 
indicator. A convenient method for clearing the entire state indicator is to 
issue a )SIC command. 



Sidetracking On Errors And Breaks 

In some APL applications, the programmer would like to bypass APL's standard error 
and break procedure (for example, to substitute messages or institute corrective 
actions). Computer— ass isted learning programs and commercial business aids are 
applications where this may be desired. Users of such applications may have little 
knowledge of APL, and messages such as DOMAIN ERR or VS FULL frustrate rather than 
he I p. 

CP-6 APL allows the programmer to overcome this problem through "sidetracking". The 
term "error control" is also used (with an understanding that break control is 
included). 

Suppose a DOMAIN ERR has been detected by APL. With sidetracking, APL searches the 
state indicator for active functions for which the programmer has decided to 
sidetrack. If a sidetracking function wants control over DOMAIN ERR, then APL 
sidetracks (branches) to the line in the function specified for DOMAIN ERR. If no 
active function wants such control, then APL issues the standard diagnostic message. 

Sidetracking is both flexible and dynamic. Different errors can be sidetracked to 
distinct lines of a function. Certain sidetracking functions may control some errors 
while other sidetracking functions control others. The system function UERS allows 
on APL program to simulate an error (which can be subject to sidetracking) by 
supplying the error number and optionally the error message. Sidetracking functions 
con also compete for control of the same error. In this case, the most recently 
invoked function gets control, and its competing predecessors never become aware that 
the error occurred. Sidetrack specifications can be changed at will. They con be 
turned on and off, the error selection can be altered, and the sidetrack branches can 
be changed; the application program itself con modify sidetracking specifications 
throughout its execution. This capability permits a simple or comprehensive 
treatment at the programmer's discretion. 
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Table 10-1 shows errors that are subject to sidetracking. Errors not listed in the 
table include SYSTEM ERR and BROKEN WORKSPACE. 

Since recovery from these errors is impossible for an applications program, APL 
retains exclusive control. See the discussion following Table 10-1 for details 
concerning certain unique errors. 

Associated with each item in Table 10-1 is on error number. Error numbers ore 
informally grouped by common classifications: statement execution errors, 
i nput— t rons I at i on errors, command errors, file input/output errors, etc. Gaps are 
provided in the error number sequence to accommodate future diagnostics. 

The items in Table 10—1 contain four cases in which APL gives up control after 
displaying on error message: 

SI DAMAGE 
name NOT COPIED 
name NOT FOUND 
name NOT ERASED 

These cases, in which command processing or function definition is in effect, must 
reach on orderly conclusion. Therefore, APL unilaterally displays the messages and 
proceeds to conclusion. (Nevertheless, sidetracking is still possible, and on 
application program might issue explanatory messages after the APL messages, as one 
alternative.) As APL proceeds in these four cases, a series of such messages could 
be displayed (but this would be unusual). APL permits sidetracking only with regard 
to the latest error known at the conclusion of this kind of processing. Using the 
execute function, for example, suppose a )COPY command occurs while sidetracking is 
in effect. Suppose also that some object, X, is missing from the copied workspace — 
X NOT FOUND is displayed; furthermore, suppose that the data found will not fit in 
the active workspace. Then the )COPY command concludes without copying anything and 
would ordinarily issue a TOO BIG message. Sidetracking would then apply in this 
example to the 7*00 BIG error and, the NOT FOUND error would be "forgotten". 

Note in the foregoing example that copying was attempted by means of an execute 
operation. This was a necessity. A function can obtain sidetracking only while it 
is actively in execution. Thus command and function definition errors can be 
sidetracked only when the function (or some function invoked by the sidetracking 
function) actually executes a command or function definition. Eva I uated-i nput might 
seem to provide another way in which a function could, indirectly, Invoke command or 
function definition activity. However, for the reason given below, evaluated input 
is not considered capable of being sidetracked (except while that input has itself 
invoked a sidetracking function). 

The execute function mokes it possible to execute via quote-quod input anything that 
could be entered via evaluated input. Quote— quod input has on advantage from the 
standpoint of error recovery. The input text con be assigned to a variable before it 
is executed. Thus, a sidetrack function con analyze this text to determine correct 
recovery action. Eva I uoted-i nput is not susceptible to this analysis; it is 
immediately interpreted by APL. 
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Table 10-1. Events Subject to Sidetracking 


Error Number 


Error Message 


1 


WS FULL 


2 


SYNTAX ERR 


3 


UNDEFINED 


4 


DOMAIN ERR 


5 


RANK ERR 


6 


LENGTH ERR 


7 


INDEX ERR 


8 


NO RESULT 


10 


IMPLICIT ERR 


15 


SINGULAR MATRIX 


16 


FORMAT SYNTAX ERR 


20 


BAD CHAR 


21 


LINESCAN ERR 


22 


TRUNCATED INPUT 


23 


OPEN QUOTE 


30 


I/O ERR fcg-xxxxx-8 


35 


DEFN ERR 


36 


SI DAMAGE 


38 


NOT CLEAR WS 


39 


CLEAR WS 


40 


BAD COMMAND 


41 


NOT SAVED. THIS WS IS name 


42 


FILE IN USE 


43 


BAD FILE REF 


44 


WS NOT FOUND 


45 


TOO BIG TOO LOAD 


46 


TOO BIG 


47 


TOO MANY SYMBOLS 


48 


name NOT COPIED 


49 


name NOT FOUND 


50 


name NOT ERASED 


51 


NOT GROUPED 


52 


SEALED WS 


53 


OLD WS. MUST EXPORT 


55 


NOT HELD 


59 


HOLD ABORTED 


61 


HOLD DEADLOCK 


62 


ENQUEUE FULL 


68 


SV QUOTA EXHAUSTED 


69 


NO SHARES 


70 


FILE SPACE TOO LOW 


71 


FILE I/O ERR fcg-xxxxx-8 


72 


FILE DAMAGE 


73 


FILE NAME ERR 


74 


NOT APL FILE 


75 


FILE TBL FULL 


76 


FILE ACCESS ERR 






78 


PACKSET NOT MOUNTED 


79 


FILE INDEX ERR 


98 


NONCE ERR 


100 


INTERRUPT 
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USM Function (Set/Query Sidetrack Matrix) 



Syntax: 

E*-QSH F 
R^E []SH F 



Parameters: 

F is a namelist containing the name of a displayable defined function. 

E is a simple 2-column motrix of integers in whicli the first column contains line 
numbers and the second column contains error numbers. 

R is an empty numeric array. 



. Oescr i pt i on: 

A sidetracking setting resembles setting a stop or trace vector. The function must 
be defined when the USM function is executed; it could even be a statement in the 
f unct ion. 

The dyadic USM function requires that the right argument contain a legal name or 
DOMAIN ERR is reported. The explicit result of dyadic USM is an empty numeric 
vector. The left argument (sidetrack matrix) must be a matrix or RANK ERR is 
reported. The second dimension of the left argument must be 2 or LENGTH ERR is 
reported. The left argument must be a simple array containing only integers or 
DOMAIN ERR is reported. 

In effect, the sidetrack table becomes port of the function's definition and is 
copied or loaded if the function is copied or loaded. Function editing has no 
influence on the sidetrack setting. Since the sidetrack table contains line numbers, 
the following precaution should be observed. If editing a sidetracking function 
alters the position of a line specified by the sidetrack table, a correct setting 
must be reissued. This is necessary to ensure that the proper line will be branched 
to if the sidetrack does take place. 

Erasing a sidetracking function erases its sidetrack setting. A sidetrack setting 
con also be removed by being replaced with an empty matrix, as in the following 
example: 

(0 2pO)DSW 'FUN* 

When a (non— empty) table is assigned for sidetracking, it consists of one or more 
rows. Each row contains a pair of integers - a line number and an error number. The 
line number designates which line of the function is to be sidetracked to (branched 
to) if the indicated error occurs. The following sample sidetrack setting specifies 
o branch to line number 9 in case of a DOMAIN ERR (error 4 in Table 10-1). 

(1 2p9 ii)USM 'FUN' 

A new sidetrack setting for a function entirely replaces any previous setting. 



Examples: 

The following example would remove FUN *s control over DOMAIN ERR. 

(2 2p9 3 9 2)DSW 'FUN' 

In this example, FUN sidetracks to line 9 for UNDEFINED or SYNTAX ERR. This 
illustrates that a sidetrack table con contain duplicate line numbers; however, it is 
useless to duplicate an error number in the same table. Only the first such number 
would be effective. 
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In the above example, FUH sidetracks on only two of the possible errors. If other 
errors occur, APL handles them in the standard manner unless some other function has 
specified sidetracking for those errors. 

A special error number, 0, exists for sidetracking on all items in Table 10-1 except 
the break (number 100). In the following example, FUN sidetracks: 

o to line 8, if a break is detected 



o to I i ne 7 , i f f/5 FULL occurs 



o to line 9, for any other error subject to control. 

(3 2p8 100 7 1 9 0)D5W 'fW 



Breaks are sidetracked only if the sidetrack explicitly includes error number 100. 

The current sidetrack matrix may be obtained by the monadic execution of the USM 
system function. In this case, the right argument is the same as in the dyadic 
usage, but the result is a simple N— by-2 matrix of integers. For example: 

USM 'FUN' 

8 100 
7 1 

9 0 



The result of monadic USM for all names other than a displayable, active defined 
function is a numeric matrix of shape (0,2). 

The following example (assuming origin 1) shows a compact way of setting several 
different error numbers to the same line. Suppose ERRLAB is the label of the desired 
line and sidetracking is set within the function FCN containing ERRLAB. 

{ERRLAB,[\ '^'iZ 3 5 8 21) DSW 'FCN' 

sets the indicated errors to sidetrack to ERRLAB (see Lamination). 

The above examples illustrate how to set sidetracks. This does not imply that the 
function FUN immediately receives control if an error occurs. If FUN is not actively 
in execution, its sidetracking is disregarded. Even if FUN is in execution, it may 
still not be given control. The error may hove occurred in evo I uoted-i nput , or FUN 
may hove called another function which has a competing sidetrack. 



Dyn£imics of Sidetracking 

A step-by-step outline reveals significant aspects of sidetracking dynamics. Assume 
a controllable error or break has occurred and APL is ready to check for 
s idet racki ng . 

Step 1: APL designates and saves the current error number, replacing any previously 
recorded error number; the line in execution, the position in this line and the text 
of the error message are also saved. For the moment, it initializes the error 
location to be line zero and an empty function name. APL points to the top (latest) 
entry in the state indicator. 

Step 2: The state entry is examined. If it is a pendent function. APL proceeds to 
Step 3. If it is an execute-operation state, APL points to the next entry and 
repeats Step 2. Otherwise, sidetracking is not applicable; so APL issues the 
standard diagnostic. 

Step 3: (Pendent function state) The error location is tested. If still initialized 
(see Step 1), the line number and name of the pendent function are recorded. The 
function's definition is tested for sidetrack setting. If it features some 
sidetracking, APL proceeds to Step 4. Otherwise, APL points to the next state 
indicator entry and repeats Step 2. attempting to find a function with a sidetrack 
setting. 
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step 4: (Sidetrack setting present) The sidetrack table is tested sequentially 
versus the recorded error number. If a match is found, or the error number is less 
than 100 or greater than 199 and the table has an error number entry for the error 
number lOOxltf^lOO (where N is the error number being reported) or the table has a 
zero error number, APL proceeds to Step 5. Otherwise. APL points to the next state 
entry and repeats step 2. attempting to find a function interested in the current 
error . 

Step 5: If the specified line number is greater than or equal to zero, then APL 
proceeds to Step 6. Otherwise, the line number is assumed to represent one of the 
special actions in Table 10-2. 

Step 6: (Sidetrack acknowledged) APL removes from the state indicator any entries it 
bypassed in reaching Step 5. This puts the sidetracking function at the top of the 
state indicator. APL then branches to the specified line number. 



Table 10-2. Sidetracking Special Action Table 


Number 


Special Action 


"1 


The state indicator is cleared to the entry before 
this function. The current error is then reported 
at the point of the sidetracking function call. 


"2 


This function explicitly requests no sidetracking 
for the error. The state indicator, however, is 
to be cleared to this function and this function 
suspended. (Debugging Aid) 


"3 


Similar to ~2 except that the state indicator is not 
cleared to the sidetrack function. The function that 
was in execution when the error occurred is suspended 
and the error is reported at the point of the error. 
(Debugging Aid) 


~ii 


When used in conjunction with an error class control, 
this allows a function to control all errors but a 
specific error. As in 

(2 2p "4 1 5 0) USM 'X' 

This setting means that ail errors other than a 
workspace full (1) will sidetrack to line 5. 


"5 


The APL session is terminated and a CONTINUE workspace is saved, 
suspending the function that had the error. 


"6 


The workspace is cleared. 



Considerations after Gaining a Sidetrack 

Once APL performs a sidetrack, it has no further interest in handling the break or 
error. Responsibility falls to the application programmer, depending on the line 
number dictated and statements supplied for the sidetracking function. Caution is 
advi sed. 

If a mistake occurs in statements entered via a sidetrack, a new error may confuse 
the intended recovery procedure. It is possible for that statement to generate the 
error being considered, leading to the same sidetrock, the same mistake, and so on 
indefinitely. WS FULL can be particularly troublesome. In some coses, the statement 
reached by the sidetrack will itself cause another WS FULL. There is no general 
solution to this potential problem, but It is a rare difficulty for two reasons. 
First, intermediate results may be discarded after any error, freeing up sufficient 
workspace for recovery. Second, more workspace may become available if state 
indicator entries are removed in reaching the sidetrack (See Step 5 above). 
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Aids for Sidetrack Users 



Eight system functions are of particular interest after an error has occurred. These 
functions are described next. 



UERN Function (Error Number) 



Syntax: 



Description: 

The result is a two-item integer vector, the first item is the latest error number 
and the second item is the line number of the function in which the error occurred. 
If the error did not occur in a defined function, the second item is 0. 



UERF Function (Error Function) 



Syntax: 
F^UERF 



Descr ipt ion: 

The result is a character vector containing the name of the function in which the 
error occurred. If the error did not occur in a defined function, the result is an 

empty character vector. 



UERM Function (Error Message) 



Syntax: 
T^UERH 

Description: 

The result is a character vector containing the text of the latest error message. 
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UERL Function (Error Line) 



Syntax : 
T*-UERL 

Descri pt ion: 

The result is a character vector containing the text of the line that was in 
execution when the error occurred. 



UERP Function (Error Position) 

Syntax: 
I*-UERP 

Description: 

The result is the integer scalar index in UERL of the error pointer. The result 
value is QtO dependent. 

UERX Function (I/O Error) 



Syntax: 
T*{}ERX 

Descript ion: 

The result is a character vector of length 12, containing the latest I/O error 
information available to APL. It represents one of the error codes given in the CP-6 
Host Monitor Services Reference Manual, v.1. (CE74). 



UERH Function (Error Help) 

Syntax: 
T*UKRU 
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Description: 

The result is a character matrix of shape N-by-120 containing the error message text 
from the system error message file pertaining to the latest CP-6 I/O error 
inf ormot ion. 

Note: APL sometimes expects I/O errors. Thus, the value reported when using []ERX 
does not necessarily indicate an error condition has occurred. 



UERS Function (Error Simulation) 



Syntax: 

MESSAGE UERS I 
UERS I 



Parameters: 

/ is a simple integer scalar in the range 0 through 19999. 
MESSAGE is a simple character vector containing on error message. 



Descr i pt i on : 

The UERS system function initiates an error report under program control that can be 
subject to sidetracking. The error simulated may be one of APL's standard execution 
errors such as DOMAIN ERR or the specific error message can be supplied. The left 
argument of UERS may be supplied only for error numbers greater than 499. Simulating 
error number 0 clears the current error status variables (.UERN , UERF, UERM, UERL , 
UERP) to their initial values in a clear workspace. 

If UERS is invoked by an active function, the error generated by the execution of 
UERS occurs in the environment of the line that invoked the currently executing 
defined function. 
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Section 11 

System Functions and Variables 



CP— 6 APL provides a complete set of system functions and variables. Each of these 
system-defined objects have names which begin with a quad (□) and are known as 
distinguished names. 

All of the distinguished names are present in an active workspace, and the values of 
the system variables are saved with the workspace when a )SAVE command is issued. 

All CP-6 APL system variables have default values in a clear workspace, may be 
modified at any time by assignment, and ore subject to the normal rules of scope. 
That is, a user— defined function may localize a system variable and subsequently 
modify it. When the function exits, the value of the system variable will revert to 
its original value. The following table lists system variables included in CP-6 APL. 



Table 11-1. System Variables 


NAME 


MEANING 


VALUE IN CLEAR WS 


RANGE 


Dcr 


Comparison tolerance 


ir"13 


Non-negative less than 
lE'lZ 


UIO 


Index origin 


1 


0 or 1 


ULX 


Latent expression 


f 1 


character vector 


UPP 


Print precision 


10 


integer in the range 
1 .. 20 


UPS 


Pos i t i on i ng 
and spacing 


"110 2 


a 4-item integer vector. 
The first two items 
ore integers in the 
range "1 to 1 . 
The last two items may 
be any integer value 
from 2*35 to "1+2*35. 


UPW 


Platen width 


device dependent 


integer in the range 
32 .. 390 


URL 


Random link 


16807 


integer in the range 
1 .. ("1+2*35) 


USA 


Stop Action 


1 1 


*EXIT' , *CLEAR* end 


USP 


Session Parameter 


1 1 


any array 



Each of the APL system variables is described in detail next. 
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QCT Variable (Comparison Tolerance) 



The relational functions (< i = > i , monadic F, I and dyadic i, fi and « involve 
comparisons that are not absolute because of the internal representation of numbers. 
□Cr is used to establish a neighborhood of equality around any particular value. For 
the relational functions, any number between B+UCT*\B and B-[y:T*\B will be considered 
equal to B. The default value for UCT is 1£'~13 which is adequate for almost all 
s! tuat ions. 

Comparison tolerance is used in APL so that the finite precision of the internal 
representation of numbers can be partly disguised. Computer arithmetic with real 
numbers can only approximate the result to numbers which are mathematically close to 
the true result. Meaningful values of UCT are real numbers in the range 0 to IE~12 
inclusive. 



UlO Variable (Index Origin) 

The Q/O variable is used by APL during indexing, the axis operator, UFX, ?, dyadic 0, 
I, i, and t. Its value indicates the index of the first value in a non-empty vector. 
The only permissible values are zero and one. The default value in a clear workspace 
is 1. 



ULX Variable (Latent Expression) 

The □LX' variable is executed (as in sULX) whenever a workspace is loaded. The 
default value in a clear workspace is on empty character vector. 



UPW Variable (Platen Width) 

All output is subject to the constraint that at most DPI/ characters will appear on a 
line. Additional characters that would have appeared on a particular line are 
printed indented on the succeeding line. The meaningful values are integers in the 
range 32 through 390. The default value in a clear workspace is the CP— 6 platen 
width setting when APL was invoked or the closest permissible value to the CP-6 
platen setting. 



UPS Variable (Positioning and Spacing) 

The value of the UPS variable controls the display (and monadic format result) of 
nested arrays. The meaning of the values are described in Section 3 under Output. 
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UPP Variable (Print Precision) 



The DPP variable is used to determine the number of digits to be used in the default 
display of numeric arrays. The meaningful values are integers in the range 1 to 20. 
The default value in a clear workspace is 10. 



URL Variable (Random Link) 

This value is used in the ? function and reset after each use such that it cycles 
through the entire meaningful range. The meaningful values are integers between 0 
and 2*35 exclusive. 



USP Variable (Session Parameter) 

When APL is invoked, USP is established with an initial value of an empty character 
vector. A new value may be specified at any time, by assignment (or a )COPY command 
containing USP in the copy list). The value associated with USP is carried across 
)LOAD and )CLEAR commands. 



USA Variable (Stop Action) 

The USA variable defines the action to be taken when a function terminates execution 
and direct input mode is entered for any reason. The default value of an empty 
character vector indicates that no action is to be token. Other valid volues of USA 
ore: 'CLEAR' which causes the workspace to be cleared, and 'EXIT' which causes APL 
to issue on )END system command. If the value of D^^ is undefined the state 
indicator is scanned until a value associated for USA is found and the associated 
action is taken. 



System Functions 

System functions ore always present in a workspace, and con be used in defined 
functions. They ore ni Iodic, monadic, or dyadic as appropriate and have an explicit 
result. In many coses, they also hove implicit results, in that their execution 
causes a change in the environment. 



Workspace Management Functions 

CP-6 APL provides a set of system functions, OCfl, UFX , UHL, UEX, UEKG, UlOK, UNC , 
UttCG, URM, URMG, UST, UTR, [15W, USTOP and UfTRACE to aid in user workspace management 
and information display. 
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Name 1 1st and Canonical Representations 



The introduction of two concepts is useful to describe the argument and results 
associated with these system functions. A nomelist is a character matrix in which 
each row represents an APL name. As an argument to a system function, a nomelist may 
also consist of a character vector of names separated by blanks. 

When o nomelist argument is required, a RANK ERR occurs if the rank of the argument 
is greater than 2. A DOMAIN ERR occurs if the argument contains on item which is not 
a character scalar. A LENGTH ERR occurs if c row contains more than 262143 columns. 
A DOMAIN ERR is also reported when a system function which only accepts a single 
name, is provided with other than a single name. Examples of legal namelists are: 

'A' fi NAMELIST CONTAINING THE NAME A 

*AB' fi NAMELIST CONTAINING THE NAME AB 

2 Zp'ABCD' fl NAMELIST CONTAINING THE NAMES AB AND CD 

'AB CD' a ARGUMENT NAMELIST CONTAINING THE NAME AB AND CD 

Canonical Representation is o representot i on of o function as a character matrix. 
Each row of the matrix represents a line of the function. The first row must consist 
of 0 valid function header. Succeeding rows if present must be valid APL statements. 

A RANK ERR is reported if the rank of the canonical representation is greater than 2. 
A LENGTH ERR occurs if a row contains more than 262143 columns. A DOMAIN ERR is 
reported if the canonical representation contains on item which Is not a character 
scalar. The canonical representation does not contain line numbers as provided by 
the function definition mode display. 



System Functions for Function Definition 

CP— 6 APL provides system functions to create, modify, and replace defined functions. 
These functions include UTRACE, DSrOP, DCR, UFX, and UAT discussed in section 7. and 
QSM in section 10 in addition to the following functions. 



ULOK Function (Lock Function) 



Syntax: 

V*-QLOK N 



Parameters: 

is a nomelist containing the names of user— defined functions in the active 
workspace. 

V is a simple vector containing the integer values 0 or 1. 



Descr i pt ion: 

The ULOK function returns a numeric vector containing 1 if the corresponding name in 
N is now 0 locked function or 0 otherwise (also see function UAT in Section 7). The 
referenced functions are locked. 
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UST Function (Set/Query Stop) 



Syntax: 



V*UST F 



R'*-V UST F 



Parameters: 



F 



is a namelist containing the name of o defined function. 



V 



is a simple integer vector. 



R 



is a simple integer vector. 



Descr i pt ion: 

For monadic UST, \i F \s a namelist containing the name of a defined function, the 
result V is the stop vector associated with that function. 

For dyadic UST, if f is a namelist containing the name of a displayable defined 
function, stop control is set on the lines indicated by V. The explicit result is 
empty vector. Also see the function $QSTOP. 

Possible Errors: 

A RAHK ERR is reported if: 

o the left argument V is not a scalar or vector. 
A DOMAIN ERR is reported if: 

o V is not a simple array containing integers. 

UTR Function (Set/Query Trace) 

Syntax: 

V*UrR F 
Yt-V UTR F 

Parameters: 

F is a namelist containing the name of a defined function. 
V is a simple integer vector. 
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UTR 

Function (Set/Query Trace) 



11 



Descript ion: 

For monadic UTR, if f is o namelist contoining the name of a displayable defined 
function, then V is the trace vector associated with that function. 

For dyadic UTR, if F is a namelist containing the name of a displayable user defined 
function, trace control is set on the lines indicated by V. The explicit result is an 
empty vector. Also see the function $QTRACE. 

Possible Errors: 

K RANK ERR is reported if: 

o the left argument is not a scalar or vector. 
A DOMAIN ERR is reported if: 

o V is not a simple array containing integers. 

Workspace Management System Functions 

The following functions are used in the management of active workspace. 



UAV Function (Atomic Vector) 



Syntax: 

X*UAY 

Parameters: 

X is a character vector of length 512. 
Description: 

The UAV function returns a character vector containing all of the possible characters 
In the APL character set. Many of these characters ore not used in CP-6 APL to 
represent printing symbols. The positions of the individual characters differ 
between implementations of the APL language. 



Exomp I e : 

□>IV[65+i27J 
ABCDEFGHIJKLHHOPQRSTUYWXYZl 



11-6 



UAV Function (Atomic Vector) 



CE38-e4 



UCPU Function (CPU Time Used) 



Syntax: 
Parameters: 

/ is an integer scalar. 
Descript ion: 

The UCPU function returns on integer scalar containing the CPU execution time used 
since entering APL. The time returned is in units of milliseconds. Execution times 
vary widely between APL implementations and the model of CPU upon which the APL is 
execut i ng. 



Example: 
3 

In this example, the time required by CP-6 APL to execute the expression Z*-5^tiE6 has 

been computed to be 3 milliseconds (or .003 seconds). 



UCVT Function (Convert) 



Syntax: 

R't-W UCVT J 

Parameters: 

J is a simple array of either all numeric or all character items. 
W is a simple integer vector of length two. 

Descript ion: 

J must be a simple array containing only numeric or only character items. (/ i s a 
simple two-item integer vector controlling the result type and values of R. The first 
item of U is one of 1, 2, 3, or 4 meaning one of the following types: 

TYPE INTERNAL BIT LENGTH MEANING 

1 1 Boolean 

2 9 Character 

3 36 Integer 

4 72 Floating Point 

The second item of 1/ is a value whose magnitude indicates the number of bits of the 
right argument to use to represent each item of the result. If the second item of W 
is less than zero, then the sign of each item of R is negative if the sign bit of a 
field is 1. A DOHAIH ERR occurs if the first item of W is not one of 1, 2, 3, or 4, 
or if J is either a nested array or index sequence. A LENGTH ERR occurs if the 
number of bits in the last dimension of J are not evenly divisible by the second item 
of W. 
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Example: 

3 9 DCVT 'ABZ' 0 CHARACTER Nu. 

65 66 90 

UAV I UBZ' 

66 67 91 

3 3 DCVT *AZ' fl CONVERT TO OCTAL 
10 113 2 

3 36 UCVT 12345678.015625 
1709378160 85B993<t592 



UDL Function (Delay) 



Syntax: 



Parameters: 

/ is a simple integer scalar. 



Description: 

The UDL function requires at least / seconds to complete. The explicit result is the 
number of seconds of delay. The delay may be shorter than the number of seconds 
specified if it is interrupted by a break. 



Example: 

DDL 6.75 

7 

DDL "60 fl NOV BACK UP ONE MINUTE I 

0 

Note that in the above example, requested delays of 6.75 and ~60 seconds were 
actually delayed 7 and 0 seconds. 



UEX Function (Expunge) 



Syntax: 

V*{]EX N 



Parameters: 

V 19 a name list. 

N is a simple integer vector. 



11-8 



UEX Function (Expunge) 
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Descript ion: 

The UEX function erases the user defined objects in nomelist A^, except groups, 

labels, and active, pendent or suspended functions. The explicit result is a logical 

vector whose I'th item is 1 if the I'ih name in N is now available for use (whether 

or not it was erased). For non-names or distinguished names or any names not erased, 
the result is 0. 



Example: 

UEX k ip'ABW 
110 1 

In the above example, the result of UEX indicates that the first, second and fourth 
names are now available for use (they have no active use) and that the third name is 
not . 



UEXG Function (Expunge GLobaLs) 



Syntax: 

V*UEXG H 



Parameters: 

V ISO name list. 

N ISO simple integer vector. 



Description: 

Same as the UEX function except that only global referents are affected. 



UFI Function (Fix Input) 



Syntax: 

V*UFI T 

Parameters: 

r is a simple character scalar or vector. 
V is a simple numeric vector. 



CE38-e4 



□f/ Function (Fix Input) 



11-9 



Descr ipt ion: 



The UFI function returns a numeric vector contolning the value of all numeric 
constants found in T that are delimited by blanks. Non-blanks in T that are not 
legal numbers are indicated by a zero value. 



Example: 

UFI '22 3^5 "100.5 ir999 lf6 0.0' 
22 0 "100.5 0 1000000 0 

Possible Errors: 

A RANK ERR is reported if: 

o r is not a character scalar or vector. 

A DOMAIN ERR is reported if: 

o T contains an item that is not a character scalar. 



UGRP Function (Return Group Members) 



Syntax: 
Parameters: 

G is a namelist containing the name of a group in the active workspace. 
N is a name I ist. 

Descript ion: 

The QdRP function returns a a namelist containing the names associated with the 
group. 

Example: 

QdRP *STAT_GROUP' 
MEDIAN 
MODE 
REG 

In this example, the name STAT_GROUP represents an APL group containing the names 
MEDIAN, MODE and REG. 
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UIBEX Function (IBEX Expunge) 



Syntax: 

R*UIBEX N 



Parameters: 

N is a namelist containing the names of IBEX variables. 
R is a simple integer vector. 



Descript ion: 

The UlBEX system function is used to expunge IBEX variables. The right argument is a 
namelist, the result is a simple logical vector containing 1 for every IBEX name that 
is now available for re— use, or 0 for the corresponding name representing an 
unavailable name (illegal name). 



Example: 

UIBEX 'STATUS* 

1 



UIBLET Function (Set/Query IBEX Variable) 



Syntax : 

R*-niBLET T 
R^T QIBLET T 



Parameters: 

T is a simple character vector. 
R is a simple character vector. 



Descript ion: 

The UIBLET system function returns or sets the value of an IBEX variable. The right 
argument is the text of the name of an IBEX variable and the left argument when 
present is the value to be assigned to that variable. Monodically, UIBLET returns 
the value of the named variable. Dyadical ly, the left argument becomes the new value 
of the varioble. 

This function con be useful when communicating with IBEX (outside of APL) or with 
other CP-6 programs. The left and right argument must be o scalar or vector or a 
RAtfK ERR is reported. A LENGTH ERR is reported if the name in the right argument 
contains more than 31 characters or if the length of the left argument is more than 
511. A DOMAIN ERR is reported if either the left of right argument contains on item 
which is not o character scaler, or if the right argument contains on illegal name. 
An error is also reported if the monadic syntax is used and the named variable does 
not currently have a value. 
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Examp I e : 

'RATE'lZ.BALANCE'lZtie.HZ' UIBLET 'NAME' 

UIBLET 'NAME' 
RATE^IZ ,BALANCE=l2ti6. 42 

) '.OUTPUT NAME 
RATE^ 12 .BALANCE" i2k6 . 42 



UIBNL Function (IBEX Namelist) 



Syntax: 

R^UIBNL 



Description: 

The UJBNL system function is used to return the names of all of the IBEX variables 
associated with this CP-6 session. The result is a simple character matrix with one 
IBEX variable name in each row. 



Example: 
UIBNL 

NAME 
STATUS 



UIDLOC Function (Identifier Location) 



Syntax: 

R*QIDL0C N 



Parameters: 

N is a name list. 

R ISO simple integer matrix having one row for each name In N. 



Descr i pt ion: 

The UIBLOC system function returns the local and global name classes for each of the 
names in the namelist at each level in the state indicator. The result contains a 
row whose length is l+pULC for each name. The name classes returned are: 

-1 Not local at this level 

0 Local but no value 

1 Labe I 

2 Variable 

3 Function 

4 Not Avai I able 
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Example: 



FZIZ] ic C A 

Flk] X R D B A 

)VARS 

A C 

UIDLOC 'A B C D F* 

2 3 2 
"12 0 

2 ~1 2 
"10 0 
"I "1 3 

The first row of the result of UIDLOC contains the volues 2 3 2 which indicote that 
the name A \s a global variable, a function local to the execution instance of the 
function F and is a variable local to the function execution of F2 . The second row 
indicates that the name B has no global usage, it is a variable local to the 
execution of F end is localized (but not yet used by) the execution of FZ. 



ULC Function (Line Chain) 



Syntax: 

V*{]LC 



Parameters: 

V is a simple integer vector. 



Descr i pt ion: 

The ULC function returns an integer vector whose length indicates the number of 
entries in the state indicator and whose values ore the line numbers of the functions 
in execution or 0 for state entries that are not defined functions. The result Is 
ordered so that the most recently initiated function has the lowest index. 



Example: 

7 F 
ID ULC 
(2] I'DLC 

7 

F 

I 

0 2 

In this example, the function F displays two lines of output. The first line 
displayed indicates that line 1 is in execution. The second line displayed indicates 
that line 2 of f is in execution followed by a state entry that is not a defined 
function (an execute state entry). 
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ULGT Function (Logon Time; 



Syntax: 



I*-ULGT 



Parameters: 



is an integer scalar. 



Desc r i pt i on : 

The ULGT function returns an Integer scalar whose value is the number of milliseconds 
that have elapsed between midnight and the time of day that APL was invoked. 



0 60 60 lOOOTOOLCr 
45000250 
12 30 0 250 

In this example. APL was invoked at 12:30 PM. 

UNC Function (Name Classification) 

Syntax: 

K*mc tf 

Parameters: 

N is 0 name I ist . 

K is a simple integer vector. 

Description: 

The DATC function returns the type of object represented by each name in namelist N. 
The /*th item of K corresponds to the I'th name in N. The value of each item of the 
result is one of the following: 

0 a name without an active referent 

1 a label 

2 a variable 

3 a function 



Example: 



4 



other (distinguished name, 
group name, or not a name.) 
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Example: 



7F7 

ONC 5 \o*ABlCF* 

2 0 4 2 3 

In the above example, the result of UNO indicates that the first and fourth names (it 
and C) are variables, the second name (S) has no current use. The third name is not 
availoble (actually 7 is not a legal name), and the fifth name {F) is a defined 
f unct ion. 

UNCG Function (Name Correspondence of Global) 

Syntax: 

K*^ca N 

Parameters: 

N is a name 1 1st. 

K is a simple integer vector. 

Description: 

The same as UNC except only Global referents ore examined. 

UNL Function (NameList) 

Syntax: 

N*QfL K 
N^T DHL K 

Parameters: 

K is a simple integer scalar or vector. 
N is a name I ist. 

T is a simple character scalar or vector. 
Descri pt ion: 

For monadic UNL, K is a simple numeric integer scalar or simple numeric vector with 
items containing the values 1, 2, or 3. The result is a namelist whose rows 
represent names whose active referents ore of each of the indicated classes as 
defined for WC . 

Dyadic UNL is the same as the monadic case, except that only names beginning with one 
of the characters in T are included in the result. 
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Possible Errors: 

A DOMAIN ERR is reported if: 

o K contains on item that is not a simple integer value 1, 2 or 3. 

A RANK ERR is reported if: 

o IT is not 0 scalar or vector. 



Examp I e : 

A^AB^Ct-CX*-0 
^AFUNCTIONV 
^FUNCTION^f 

UNL 3 
AFUNCTION 
FUNCTION 

'AB* QNL 2 3 

A 

AB 

AFUNCTION 



UOtIL Function (Online) 



Syntax: 

I*-\]pNL 



Parameters: 

/ is an integer scalar value. 



Descript ion: 

The UONL function returns an integer scalar whose value is 1 if the current APL 
session is in timesharing mode or 0 if the session is in batch processing mode. 

This function allows programs to determine whether to provide prompts for input or to 
allow o timesharing user to make corrective actions in some situations and provide 
default actions in batch. 



Example: 

UONL 

1 
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UOVH Function (Overhead Time) 



Syntax: 



Parameters : 

/ is on integer scalar. 



Descr ipt ion: 

The WVH function returns an integer scalar containing the CPU execution time 
overhead since entering APL. The time returned is in units of milliseconds. 
Overhead time is defined as CPU time expended while executing within the CP-6 
operating system and not while executing within the APL process. 



Example: 

DOVH 0 UOVH ,DOVH .UOVH .UOVH 

227 

231 231 231 231 

In this example, the first line of output indicates that 227 milliseconds of CPU time 
of overhead hove been used since entering APL. In the second line of output, the 
overhead CPU time is constant since all four values are obtained without incurring 
any monitor service time. The different values reflect the monitor processing 
involved in writing the output to the terminal. 



URM Function (Room) 



Syntax: 

V*URH N 



Parameters: 

N i s a name list. 

V is a simple integer vector. 



Description: 

The URM function returns an integer vector whose /*th value is equal to the number of 
bytes of workspace occupied by the /*th name in N. 



Exomp I e : 

URH U*QfL 2 3 

A 

C 
F 

16 16 U4 

In this example, the name A occupies 16 bytes, C occupies 16 bytes, and F occupies 
144 bytes of workspace. Expunging these names does not necessarily return that 
amount of workspace because in CP-6 APL values can be shared with other names. 
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URMG Function (Global Room) 



Syntax: 

V*URMG N 

Parameters: 

N ISO name list. 

V is a simple integer vector. 

Descr i pt i on : 

Like [^M except that the size in bytes is of the global referents of the names in H. 
USCT Function (Session Time) 

Syntax: 

I*USCT 

Parameters: 

/ is on integer scalar. 
Descri pt ion: 

The QSCr function returns an integer scalar whose value is the number of milliseconds 
that have elapsed since APL was invoked. 

Examp I e : 

0 60 60 lOOOT|>[]SCr 
16257<(0 
0 27 5 7<»0 

In this example. 27 minutes, 5 seconds, and 740 milliseconds have elapsed since APL 
was invoked. 
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QSI Function (State Indicator) 



Syntax: 



Parameters: 

X is a character vector. 



Description: 

The USI function returns a character vector with the same contents as the display of 
the )SI command. Carriage return characters are used to separate each line of the 
state indicator display. 



Exomp I e : 
V F 

[1] 1+1 n A LINE TO STOP ON 

7 

1 X^TOP 'F' a STOP ON LINE 1 
F a SUSPEND F 

Fll] 

)SI 
fill * 

Fll] * 
6 

F a SUSPEND F AGAIN 

ft 11 

)SI 
Fll] * 
Fll] * 

Fll] * 
ft 11 * 
13 

In this example, the function F has been suspended by setting a stop on line 1. The 
result of the OS/ function contains the same information as displayed by the )SI 
command. 
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USITEID Function (Site ID) 



Syntax: 

T*{]SITEID 

Description: 

The USITEID ni Iodic function returns the site-id of the current CP-6 system as o 6 
item character vector. 

Example: 

USITEID 

LJtBOOl 

USITENAME Function (Site Name) 

Syntax: 

T<-USITENAHE 

Descript ion: 

The USITENAME niladic function returns the CP-6 site name as a character vector. 

Example: 

USITENAME 
LADC LeSA 

USTEPCC Function (Step Condition Codes) 

Syntax: 

USTEPCC I 

Parameters: 

/ is a simple integer scalar. 

Descript ion: 

The USTEPCC function specifies the value for the step condition code when APL exits. 
The last value specified will be used. This value may be interrogated in IBEX 
statements that follow the execution of APL. 
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Example: 

USTEPCC k 



USYSID Function (Sysid) 

Syntax: 

I*{]SYSID 

Parameters: 

/ is a simple integer scalar. 

Descr ipt ion: 

The [^YSID nlladic function returns the sysid of the current CP-6 user as a scalar 
integer. This number is used by the CP-6 system to identify output to devices (like 
line printer output) and to schedule and run botch jobs. 

Example: 

USYSID 

38200 

UTS Function (Time Stamp) 

Syntax: 

v*Brs 

Parameters: 

V is a 7-item integer vector. 
Description: 

The UTS function returns a 7— item integer vector whose individual items are the 
current year, month, day, hour, minute, second, and millisecond. The actual time 
returned depends on the setting of the time in the CPU that CP-6 APL is running on. 

Example: 
UTS 

l9Bk 7 1 11 15 15 450 

In this example, the current date and time is July 1, 1984 at 11:15 AM and 15.450 
seconds. 
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UTT Function (TerminaL Type) 



Syntax: 

I*^QTT 



Parameters: 

/ is a simple integer scalar. 



Descript ion: 

The UTT function returns on integer scalar whose value indicotes the character set 
that APL uses to output to the terminoi (or home device). The value returned by this 
function reflects the value determined when APL was invoked or the most recent value 
specified by the )TERMINAL system command. The possible values for terminal type are 
indicated by Table 11-2. When the output device is not capable of producing the full 
APL character set, ASCII mnemonics (defined in Appendix B) are used to output those 
characters which are not available. The choice of the mnemonics used for output 
depend upon whether the terminal type indicates support for lowercase and 
overst r i kes . 



Table 11-2. CP-6 APL Terminal Types 


Number 


Descript ion 


1 


Full APL character set 


2 


ASCII character set, upper case only 


3 


ASCII character set, upper case only, overstrikes 


4 


ASCII character set. upper and lower cose 


5 


ASCII character set, upper and lower cose, overstrikes 


13 


Full APL character set 


14 


Full APL character set 



Example: 

□rr 

1 



UUA Function (User Account) 



Syntox: 

T*OUA 



Parameters: 

T is a simple character vector of length 8. 
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Descri pt ion: 

The nUA function returns a charocter vector containing the CP-6 account number under 
which the APL user is logged in. 

Example: 

IZ3TEST 
8 

UUL Function (UserLoad) 

Syntax: 
Parameters: 

/ is a simple integer scalar. 
Oescript ion: 

The nUL function returns an integer scalar indicating the number of users that are 
currently using the CP-6 system. 

Example: 

115 

QVl Function (Verify Input) 

Syntax: 

V*-UVI T 

Parameters: 

T is a simple character scalar or vector. 
V is a simple numeric vector. 

Descript ion: 

The result has the same length as QFI T. Each item of V is either 1 meaning that the 
corresponding item in Qf/ T is a valid representation of a number or 0 meaning that 
the corresponding item of Qf/ T does not represent a number. 
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Example: 

INPUT*-' ZZ 3^5 "100.5 15999 lEG 0.0' 

□V/ INPUT 
10 10 11 

(Qy/ INPUT)/UFI INPUT 
22 ~100.5 1000000 0 

Possible Errors: 

A RANK ERR is reported if: 

0 r is not a scalar or vector. 

A DOMAIN ERR is reported if: 

0 T contains an item that is not a character scalar. 
UVERSION Function (Version) 

Syntax: 

Tt-UVERSION 

Description: 

The \JVERSION ni Iodic function returns the current version of APL as a character 
vector. 

Example: 

{JVERSION 

DOO 

UWA Function (Workspace Available) 

Syntax: 

l*OfA 

Parameters: 

1 is on integer scalar. 
Description: 

The Qt/A function returns an integer scalar whose value indicates the number of unused 
bytes in the active workspace. This space is available for the storage of data and 
defined functions. 
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Example: 
1048360 



UVSID Function (Workspace Identifier) 



Syntax : 

T*0/SID 



Parameters : 

7 is a character vector. 



Descript ion: 

The [ffSID function returns a character vector containing the name of the active 
workspace. 



Examp I e : 

CLEAR WS 
8 

)LOAD APLANAR.X 
APLANAR SAVED 12:18 NOV 10 '8<( 

APLANAR.X 
9 



Shared Variable System Functions 



CP-6 APL provides the ability to share values between users of the system via the 
shared variable facility. A variable may only be shared by two users although each 
user con potentially share many (currently 16) variables. When a shared variable is 
used, it is indistinguishable from any other variable. It may be assigned a value 
and its value may be referenced. At any time, a shared variable has only one value, 
that is, the last value assigned by one of the partners. 

All variables (including shared variables) have a degree of coupling associated with 
them which indicates the status of any shares associated with them. The degree of 
coupling indicates whether a variable is shared or not shared. The degrees of 

coupl i ng ore: 

0. this name is not currently a shared variable 

1. this name is a shared variable that has been offered but not yet accepted by 
another user. 

2. this name is a shared variable that has been offered and matched (accepted) by 

another user. 

The term processor is often used to describe each of the partners sharing a variable. 
In this respect, each processor is identified by the account it is logged on to and 
on optional string of 12 characters that enables multiple users logged onto the same 
account to simultaneously use the shared variable facility (see USVH). Using the 
functions USVQ or dyadic USVO before a unique identification has been established 
results in a NO SHARES error being reported. 
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Namelists for the shared variable functions are slightly different than namelists 
used with other system functions. For shared variable functions, a vector is treoted 
as o one row matrix. Each row of a shared variable function namelist may contoin one 
or two names. The first (or only) name in each row designates the name to use for 
the shared variable in the active workspace. The second (or only) name in the row 
designates the name that is to be matched by the sharing process. This permits a 
single shared variable user to shore the name A with many processes where in fact 
each instance of a share actually references o unique (different) name in the user's 
workspace. 

The following are the shared vorioble system functions. 



USVC Function (Shared Variable Controls) 



Syntax: 

R*-USVC V 
R^C USVC H 



Parameters: 

N ISO name I ist . 

R is a simple integer matrix of shape N-by-4. 

C is a simple logical scalar, one-item vector, four-item vector or N-by-4 matrix. 



Descript ion: 

For monadic USVC , the explicit result is an array of shape i(~l*pN) ,k) giving, in 
each row, the current combined shared-variable access control vector for the 
corresponding rows of N. For a row which does not denote the name of a variable with 
a degree of coupling of at least one, zeros are given. 

For dyadic DSVC, the effect is to set the access controls. The explicit result is on 
array whose shape is {(~HpN) ,k) and whose value is the new combined shared variable 
access control for the corresponding rows of N. The USVC function adds the active 
workspace contribution to the shared variable access control vector. Setting this 
vector permits two separate processes to coordinate (or synchronize) their use of o 
shared variable. The access control vector for a shared variable is a vector of four 
items whose values are 0 or 1 to turn specific controls off or on. 

When a process is blocked from accessing or setting a shared variable by the access 
control vector, it will wait until the varioble's state has changed to on unblocked 
state before proceeding with execution. The positions (in origin 1) of the access 
control vector and their meanings are: 



1. If 1, then once the shared variable's value has been set in the active workspace, 
the partner (the other sharing process) must reference it before the variable con 
be set again in the active workspace. 

2. If 1. then once the shared variable's value has been set by the partner, the 
active workspace must reference it before the partner can set the value again. 

3. If 1, then once the shared variable's value has been referenced in the active 
workspace, the partner must set a value before the active workspace can reference 
it again. 

4. If 1, then once the shared variable's value has been referenced by the partner, 
the octive workspace must assign a value before the partner can reference it 
agai n. 
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NOTE: Both sharing partners contributions are combined to obtain 
the current settings of the access control vector. 



Examp I e : 

USVC 3 2p' BA BJ SO * 
0 0 0 0 
110 0 
0 0 11 

1 USVC 3 3p'BA BJ SO • 
0 0 0 0 
1111 
1111 

0 0 11 USVC 2 Zp'BJ SO • 
0 0 11 
0 0 11 

(2 4pl 1 0 0 0 0 1 1) USVC 2 3p'BJ SO ' 
110 0 
0 0 11 



USVO Function (Shared Variable Offer) 



Syntax : 

Rt-USVO If 
Rt-p USVO N 



Parameters: 

N is a name! ist. 

R is a simple integer vector. 

P is a character scalar vector or matrix which identifies one or (.^/"lipN) 
accounts. 



Descr ipt ion: 

For monadic USVO , the explicit result is a numeric vector giving the degree of 
coupling for each row of tfi 2 if shared; 1 if there is an unmatched offer to another 
processor; 0 if not offered. 

For each row of A^, dyadic USVO tenders an offer to the corresponding account if the 
first (or only) name in that row was not previously offered and is not already in use 
OS the name of an object other than a variable. The explicit result is a vector 
giving the degree of coupling in effect after the offer for each name or pair. If a 
second name is used, the second name (surrogate name) is used only for matching 
offers. An empty vector P is used to denote a general offer: an offer to share a 
variable with any account whose offer otherwise matches. 

The left argument must be a vector of length 0 through 20 or on N-by-20 matrix of 
processor identifications. The first 8 characters of a processor identification is 
the logon account and the remaining 12 characters are the name specified in the right 
argument of [I^VH . 
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Examples: 



USVO 2 2p'A B C • 

0 0 

'905APL' USVO 2 2pU B C • 

1 1 

USVO *A* 

I 

USVO 'A X* 

0 

USVO *A B' 

1 

The above example demonstrates the offer of two variables (A and C) to account 
905APL. Account 905APL would see the offers of names B and C from this account. 



Possible Errors: 

A DOMAIN ERR is reported if: 

o a row of contains other than one or two variable names. 
A SV QUOTA EXHAUSTED is reported if: 

o more offers were made than the quota allotted by the system. 

A LENGTH ERR is reported if: 

o a processor identification has more than 20 choracters. 

o the number of processor identifications is not equal to 1 or the number of names 
being offered. 



USVQ Function (Shared Variable Query) 



Syntax: 

R^USVQ P 



Parameters: 

P is a character scalar or vector. 
R is a simple character matrix. 



Descript ion: 

When P is non-empty, the result Is a character matrix of names offered by account P 
to this user, either explicitly or generally, but not currently shared. If P is an 
empty vector, the result is a vector which identifies any accounts with unmatched 
offers to share variables with this user. 
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Example: 

□5^0 WHO IS OFFERING US SOMETHING 

ARES 

ERSTEST 

In this example, two accounts are found to be offering the current APL user variables 
to share. In the following example, the shares offered by account 905APL ore matched 
using USVO. 

P^OSVQ 
P 

905APL ARES 
ERSTEST 

N*€SVQ Pll;] 
N 

STATUS 
DATA 

Pll',] USVO N 

2 2 



USVR Function (Shared Variable Retract) 



Syntax: 

R*-nsVR N 



Parameters : 

N i s 0 name list. 

R is a simple integer vector. 



Descr ipt ion: 

Ends sharing of any variables named in A^. The result is the degree of coupling before 
retraction (compare QSVO, above). This function may cause a US FULL error to occur 
obtaining the current value of the names being retracted. 



Examples: 

USVO W a PRINT 2 IF A IS SHARED. 

2 

USVR *A* 

2 

USVR W a IT IS NOT SHARED NOW. 

0 
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USVS Function (Shared Variable State) 



Syntax: 

Parameters: 

N IS a name list. 

R is a simple integer matrix of shape N-by-4. 
Description: 

The result is o numeric array of shape ((~lipV),<l) giving in each row the current 
shared variable state matrix for the names in tf. For variables that are not currently 
shared their state is given as all zeros. 

Each row of the result of USVS has four possible values: 

0 0 0 0 this is not o shared variable 



0 0 i 1 value set by one processor and has been 
referenced by the other. 

0 10 1 value set by partner, but not yet referenced 
in the active workspace. 

10 10 value set in active workspace, but not yet 
referenced by the partner. 



Examp I e : 

USVS W 
0 0 11 

USVS W 
10 10 



USVM Function (Shared Variable Process Name) 



Syntax: 

I*USVN T 

Parameters: 

r is 0 simple character scalar or vector. 

/ is the simple integer scalar containing the volue 0 or 1. 
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Descript ion: 

If shared variables are to be used by multiple users on the same CP~6 account, then 
this function permits each user to uniquely identify their own process. T is a 
vector of up to twelve characters. If a unique identifier is established the result 
is 1. If there are currently any shares offered by this process or if the value 
specified in T does not create a unique identifier, the result is 0. If successful, 
this process is uniquely identified by the eight character CP->6 account followed by 
12*7'. 



Example: 

DSVH 'BRUCE' 

1 

"USVO 'A' 

1 

USVN 'HE' 

0 

In the example above, the second execution of USVIf returned 0 because a name (A) was 
currently shared. 



Possible Errors: 

A SV QUOTA EXHAUSTED error, is reported if: 

o an attempt is made to use shared variables before establishing a unique 
identifier (the default is blanks). 



Use Function (State Change) 



Syntax: 



Descr I pt i on : 

The Use function causes execution of the current line to halt until the state of one 
of this processes shared variables changes or an explicit offer is made to this 
process. The result is 1 if a unique processor identifier exists and zero if one 
does not. 



Text Editing System Functions 

CP-6 APL provides six text editing functions which facilitate the examination and 
modification of character vectors. 
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UTIX Function (Text Index) 



Syntax: 

R*^[}TIX T SDV TOY DDV 



Parameters: 

T must be a simple character vector containing the string to tokenize. 

SDV must be a simple character scalar or vector defining those characters that 
are token separators. 

TDV must be a simple character scalar or vector defining those characters that 
ore single character tokens and token separators. 

DDV must be a simple character vector defining those character pairs that create 

delimited character strings. 

R is an N— by-2 integer matrix containing starting positions in the first column 
and lengths in the second column. 



Descr i pt i on : 

The UTIX function returns an integer matrix of N rows and 2 columns. The first 
column contains the starting index of each token in T, The second column contains the 
corresponding length of each token in T. 

The definition of o token in T is governed by the arguments SDV, TDV, and DDV. The 
SDV items are token separators and ore never tokens themselves (for example, blanks 
are skipped this way). The TDV items are token separators and ore also single 
character tokens themselves (like + is in APL) . The DDV items are token seporotors 
and also create a delimited token (like quote strings in APL). Finally, characters 
not appearing in SDV, TDV, and DDV are a single token when occurring consecutively 
(like identifiers In APL). 

The scan of T starts at the first index position and continues until a character from 
the SDV, TDV, and DDV vectors is found or the last index position of T has been 
examined. The order of evaluation is as follows: 

o Characters in T which occur in the SDV vector ore simply skipped over when they 
are encountered. 

o When the character encountered is not in the SDV, DDV, or TDV vectors, the vector 
T Is scanned from this point until a character in one of those vectors is found. 
A new row is added to the result indicating the position of the first character 
not in SDV, TDV, or DDV and whose length includes the characters up to but not 
including the character found that are in SDV, TDV, or DDV. 

o When the character encountered is in the TDV set, a token is added that indicates 
the character in TDV that was encountered. 

o When the character encountered is in the DDV set, a delimited string token is 
added to the result. The delimited string is defined by treating the DDV vector 
as an by 2 matrix and using the first character in each row as a delimited 
string starter and the corresponding second character in the same row as the 
terminator. If the delimited string starter and terminator are the same 
character, it may appear within the string by doubling it. All characters 
between the string start and end are treated as a single token. 

If the delimited string starter and terminator are separate characters, the first 
terminator character found terminates the delimited string. 

o The scan of the vector T continues, searching for characters in the SDV, DDV, and 
TDV sets until the last index of the vector T is scanned. 
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DDV need not be specified if empty, and DDV and TDV need not be specified if both are 
empty. 



Exomp I es: 

The following examples use the LIST function to display the tokens returned by the 
UTIX function. It works only in origin 1 and displays one token per row with the "." 
character indicating characters which are not part of the actual token. 

7R^A LIST B;J;K 
[IJ /?<-('. •,i«)tl + (5[;l]o.V)x^fo.>J<--l + ir/if^5[j2]] 
7 

The first example demonstrates using blanks and commas as delimiters which are not 
themselves delimiters. 

L LIST UTIX (L^'THIS IS A, TEST') • 

THIS 
IS. . 
it. . . 

TEST 

The next example demonstrates using a dieresis character to indicate a delimited 
string. 

L LIST QTIX {L<-'THIS IS "A TEST""S"-*-WOW ,k' ) • • 

THIS 

IS 

"A TEST""S" 
*WOU,k 

Notice that in the above example, the dieresis is doubled within the token to 
continue the production of the token. The following example demonstrates using token 
separators which are tokens themselves. 

L LIST QTIX (L^'THIS IS "A TEST""S"^WOW .k') • • •+,' 

THIS 

IS 

"A TEST" "S" 

+ 

WOW 

li 

In the above example, + and , are token separators and appear as tokens. The 
character " is a delimited token character in the above example. 



Possible Errors: 

A DOMAIN ERR is reported if: 

o G terminating character cannot be found in the T string, 
o a DDV or TDV character appears more than once in SDV , DDV or TDV vectors, 
o a delimited string terminating character is found that is not within a delimited 
st r i ng . 

o T, SDV, TDV, or DDV contains any item that is not a simple character scalar. 

A RAHK ERR is reported if: 

o SDV or TDV is not a scalar or vector, 
o r or DDV are not vectors. 

A LENGTH ERR is reported if: 

o the length of DDV is not a multiple of 2. 

o the right argument to UTIX contains more than 4 items or fewer than two items. 
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UTLEX Function (Text Lexemes) 



Syntax: 

R*UTLEX T SDY TDV DDV 



Parameters: 

T is a simple character vector containing the string to tolcenize. 

SDV Is o simple character scalar or vector defining the token separator 
chorocters. 

TDV is o simple character scalar or vector defining the single character tokens. 

DDV is a simple character vector defining the character pairs that create 
del iffli ted tokens. 

R is a vector of character vectors. 



Description: 

This function tokenizes the string T, returning a vector where each item was a token 
found in T. The tokenization uses the same method as the UTIX function. 



Example: 

p Z^UTLEX 'THIS IS A TEST' » • 
THIS IS A TEST 

p U*-UTLEX 'TOMATOES^FRU IT .SALMON ARE FISHY' ' ' ' = 
TOMATOES = FRUIT , SALMON ARE FISHY 
7 



USSS Function (Substring Search) 



Syntax: 

R*^SS T SS 
R*USSS T SS FCOL 
R*{]SSS T SS FCOL LCOL 

Parameters: 

r is a simple character vector. 

2^5 is a simple character vector. 

R is a simple integer vector. 

FCOL is 0 simple integer scalar index of T. 

LCOL is a simple Integer scalar index of T. 
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Description: 



The result is a vector of the starting indices in f of each non-overlapping 
occurrence of SS. If the string 55 does not occur in T then the result is an empty 
vector. 

FCOL and LCOL frame the indices of f to be searched for occurrences of 55. FCOL is 
the first index of T and LCOL is the lost index of T that will be searched for an 
occurrence of 55. When not specified FCOL defaults to D/O and LCOL defaults to 
(pD-H-D/O. 



Examples: 

TV is a vector of length 100. 

R*-nSSS TV *BOB* provides the starting indices of all occurrences of 'BOB* in TV. 

R-^USSS TV 'BOB' 30 provides the starting indices of 'BOB' in TV from TV120] to the 
end of TV. 

R*USSS TV 'BOB' 30 60 provides the starting indices of all occurrences of 'BOB' in TV 
from n^[301 to TV160]. 

The result R, FCOL and LCOL are origin dependent. 



Possible Errors: 

A DOMAIN ERR is reported if: 

o the right argument is not a 2. 3. or 4 item list, 
o r or S5 is not a character scalar or vector, 
o FCOL or LCOL are not integer indices. 

A LENGTH ERR is reported if: 

o FCOL or LCOL are not scalers or one— item vectors. 

An INDEX ERR is reported if: 

o FCOL or LCOL are not valid indices of T. 



USSR Function (String Search and Replace) 



Syntax: 



R*QSSR 
R*USSR 
R*-USSR 



T SS RS 

T SS RS FCOL 

T 55 RS FCOL LCOL 



Parameters: 



T 



is 0 character vector. 



RS 



is a character vector. 



is a character vector. 



R 



is a character vector. 



FCOL 



is a simple integer scalar index of T. 



LCOL 



is a simple integer scalar index of T. 
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Descript ion: 

The result is a choracter vector like T except that oil non-overlapping occurrences 
of 53* are reploced by RS. FCOL end LCOL indicate the ronge of indices of T subject 
to replacement. That is. only occurrences of 55 in the range FCOL*-iLCOL-FCOL are 
replaced. 

Examples: 

TV is a character vector containing names separated by blanks. 
R4-USSS TV ' ' UAV113^I0] replaces all blanks with carriage returns. 

R*^[]SSS TV ' ' CMl^[13+D/0] 20 replaces blanks from TV120] to the end with carriage 

returns. 

R*-USSR TV • » 0>(V( 13+0/01 20 30 replaces blanks from TVIZO] through TV130] with 
carriage returns. 

R'f-USSR TV 'BOB' 'ROBERT' replaces all occurrences of 'BOB' with 'ROBERT'. 
R*^DSSR TV 'PIERRE' " removes all occurrences of 'PIERRE' from TV. 

USRP Function (Substring Replace) 

Syntax: 

R^RP T RS FCOL LCOL 

Parameters: 

7 is a character vector. 

RS is a character scalar or vector. 

FCOL is an index of T. 

LCOL is an index of T. 

R is 0 character vector. 

Description: 

The result is a character vector like T with the location TILCOL) through TILCOL] 
replaced by RS. 

Examples: 

DIO^I 

TV^'THE PRICE OF PRODUCT-NAME IS' 

RS<-'WHEATIES' 

R*{]SRP TV RS 14 25 

R 

THE PRICE OF WHEAT I ES IS 
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Possible Errors: 

A DOMAIN ERR is reported if: 

o the right argument is not a four item list. 

o 7 is not o chorocter vector. 

o RS is not o character vector or scalar. 

o LCOL or FCOL are not numeric scalors or 1-item vectors. 

An INDEX ERR is reported if: 

o FCOL>LCOL or if FCOL or LCOL are not valid indices of T. 



USCP Function (String Compare) 



Syntax : 

R*-DSCP iA;B) 

Parameters: 

A is a character vector. 
B is a character vector. 

Description: 

The QSCP function returns a two item numeric vector, the first item of which is 0 if 
A is equal to B, or 1 if it is greater than B, or 2 if it is less than B. The second 
item of the result is the first index in it that A[R[2]]¥B[R[2]] or if A is equal to 
B, then R[2]*-~l. If A is longer than B and every item of B is equal to every item of 
it, then Rt-Z ~1. 

Possible Errors: 

A DOMAIN ERR is reported if: 

o the right argument is not a two item list, 
o ^ or £ is not a character vector. 

Terminal l/Q System Functions 

These system functions return information about or control a terminal session. 
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UTIN Function (TerminaL Input) 



Syntax: 

/ UTIN T 



Parameters: 

T is a simple character vector or scalar. 
/ is a simple integer scalar. 



Descript ion: 

The right argument must be a character vector which replaces the current terminal 
re-read line. If the optional left argument is present when the re— read line is 
recalled, the value of the left argument is used as the column to position to. 



UTATTR Function (TerminaL Attributes) 



Syntax: 

VtUTATTR 



Description: 

The UTATTR function returns a simple integer vector containing terminal status 
information. The vector may in a future release be extended to contain additional 
information. Currently the vector contains: 

1 Line speed (CPS) 

2 Parity (even=2, odd=1 , none=0, one=3, 2ero=4) 

3 Dial— up/hardwi red/foreign net (0=dial— up, 1=hardwire, 2=NET) 

4 Normal/multi-drop (0=normal, 1=multi) 

5 Character set (0=ASCII, 1«=bit paired. 2=type paired) 

6 Lowercase=1 

7 Screen width (characters) 

8 Screen height (lines) 

9 Blank erases (1=yes, 0«no, 2«=not applicable) 

10 Scroll (0=no, 1=yes) 

11 Wrap (0=no, 1=yes) 

12 Retypovr (0«no, 1»=yes) 

13 Editovr (0=no, 1«sves) 

14 Echo (0=no, l-yes) 
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UTTIME Function (Terminal Timeout) 



Syntax: 

OTTIHE If 

Parameters: 

If is a simple integer scalar. 

Descr 1 pt I on : 

The UTTIME function sets the timeout period in seconds for terminol reads. After a 
terminal read is issued, the terminal user must complete input in N seconds or an I/O 
error will be reported. The I/O error is, of course, sidet rackable. The read 
timeout may be reset by setting the timeout value to 0. 

UTECHO Function (Terminal Echo) 

Syntax: 

UTECHO L 

Parameters: 

L is the simple integer scalar value 0 or 1 . 
Descript ion: 

If L is zero, then terminal reads will not echo. If L is one. then characters typed 
at the terminal will echo. 

UTSQZ Function (Terminal Mnemonic Translation) 

Syntax: 

R<-I UTSQZ V 

Parameters: 

/ is the simple numeric value 0 or 1 . 

V must be a simple character scalar or vector. 

R is a simple character vector. 
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Descri pt i on: 

If the value of the left argument is 1 then the result of this function is a 
character vector containing the text in the right argument translated into internal 
APL text. This function resolves all valid overstrikes and mnemonics into single 
characters . 

If the value of the left argument is 0, then the result of this function is a 
character vector containing the text in the right argument translated Into external 
ASCII suitable for blind output. This function generates mnemonics for the internal 
APL characters that are not representabte with the currently set terminal type. 

This function is designed to aid in the use of blind I/O and APL characters with 
blind I/O. 



UTWINDOW Function (Terminal Windows) 



Syntax: 

M*UnfINDOW 



Parameters : 

H is a matrix of shape N-by— 8 containing information about each of the currently 
defined logical devices that refer to the terminal. 



Descr i pt i on : 



The result of the UTWINDOW function is a matrix which has one row for each logical 
device that refers to a terminal (device DC). The information returned indicates the 
positioning and size of each window associated with the device, and whether or not 
the window can be used to create another window. 



Table 11-3 summarizes the contents of the result matrix. Note: A future release of 
CP-6 APL may return additional information by adding trailing columns to the result 
of this function. 



The logical terminal devices 1, 98, and 99 always start a session referring to the 
same window. The system command )ILDEV may be used to create additional logical 
devices or to modify the definitions of existing devices. The )SET command may be 
used to direct APL input/output or blind I/O to any logical device. IBEX LDEV 
command options include the ability to specify a window size and position relative to 
the window being used to create the new window. 



Table 11—3. Window Column Descriptions 


Co 1 umn 


Descr i pt i on 


1 


Contains the logical device number. For 
example, if this value is 98, then the remaining 
columns of this row describe the device UC98. 


2 


Contains the line number on the screen of 

the top line of the window. The top-most line on the 

screen is 1. 


3 


Contains the column number on the screen 

of the left side of the window. The left-most column 

on the screen i s 1 . 


4 


Contains the number of lines in the window. 


5 


Contains the width of the window. 
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Table 11—3. Window Column Descriptions (cont.) 


Col umn 


Descript ion 


6 


Contains the minimum number of lines that 
must be available for this window. This value limits 
the number of lines that may be taken from this window 
to form 0 new window. 


7 


Contains the minimum width that must be 
available for this window. This value limits the 
number of columns that may be token from this window 
to form a new window. 


8 


Contains either the value 0 indicating that the window is 
removable, or the value 1 indicating that the window is 
not removable. 



Examp I e : 

pZ*UTWIl/DOW 

k 8 

Z 

98 13 1 12 80 0 0 0 
1 13 1 12 80 0 0 0 

99 7 1 6 80 0 0 0 
5 11 6 80 0 0 0 

In the preceding example, the APL session has 4 logical devices known as UC98, UC01 , 
UC99 and UC05. Logical devices 1 and 98 share the same window on the screen, 
beginning at row 13, column 1. The window is 12 lines long end 80 columns wide, have 
no minimum length or width, and are removable. 
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Section 12 

CP-6 APL File I/O 



CP-6 APL provides access to all CP-6 file types. Records within these files con be 
read or written as non-APL records, APL dotablock records, or APL component records. 

APL dotablock records are read and written along with the data type, rank, and 
dimensions. This permits arrays to be written to a file and later read back as the 
same array. 

APL component records (the default) are read and written with the data type, rank, 
dimensions, timestamp, and account identifier of the user that wrote the record. In 
addition to the capability associated with dotablock records, there is a system 
function which operates on this record format to obtain the component information 
(timestamp and account identifier). Figure 12-1 shows the component record format 
used by APL. 

A dotablock record has similar format except that the first nine words of the 
component record format are omitted. 

Non-APL records are typically files created by other CP-6 programs. Non-APL records 
may be read or written in a number of ways. The easiest method is to treat the 
record contents as o simple character vector when reading and writing the raveled 
data. This form excludes APL's internal type, rank, and shape information. Using 
this mode, datatype conversions ore the programmer's responsibility. Other functions 
(such as [yjVT and i) are available to aid in the datatype conversions. 

The APL file I/O record types and descriptions ore summarized in Table 12-1. The 
record type numbers indicated in this table ore used to indicate the type of record 
to read or write. 

When records ore read or written, an encryption seed may be specified to protect the 
data in the file. If the wrong seed is provided on a read of a component or 
dotablock record, APL informs the user that this is NOT AN APL FILE. If a non-APL 
record is read with an incorrect seed, the data returned is an encrypted version of 
the actual data. 

Records within a file con be accessed (reod or written) sequentially or by record 
identifier. The record identifier can be specified as on integer number in the range 
1 through 134217726 or as o character vector of 1 to 255 characters. Record numbers 
need not be contiguous; record number 3 can be followed by record number 10099. New 
records con be Inserted in the future and existing records may be deleted (or 
dropped) . 

Up to 31 files can be accessed simultaneously. Each file is known to APL by its 
stream number which is specified when opening (or tying) the file. Stream numbers 
are integer values in the range 1 through 34359738367. Once a file is opened, it 
remains open until it is closed using one of the functions UFCLOSE, UFCLEAR, QFERASE 
or until the APL session ends. 

A file stream is not affected by changing the active workspace. In particular the 
system commands )LOAD and )CLEAR have no effect upon the files which have been 
opened. 



CE38-e4 



CP-6 APL File I/O 



12-1 



Word 



0 


DATE (6 chars) 












UNUSED 


2 


TIME (8 chars) 


4 


ACCOUNT (8 chars) 


6 


USER NAME 








12 CHARACTERS 




9 


TYPE 


RANK 


SIZE 


IN WORDS 


10 


UNUSED 


11 


DIMENSIONS (if any) 




DATA (if any) 



Figure 12-1. File I/O Component Record Format 

CP-6 file management provides access controls to prevent unauthorized file access. 
Each file may be passworded and various levels of access are possible once the file 
is open. For example, READ access permits accounts to be specified that may only 
read records, WNEW access permits accounts to write new records, UPDATE allows 
accounts to replace existing records. For more information on file access see the 
UFSTAC and QFRDAC functions. 

When CP-6 files are created, the system allocates an initial extent and as the file 
space is used up, the CP-6 system automatically extends the file until the file space 
limit for the account or packset is used up. Thus, in CP— 6 APL there is little need 
to worry about file size when allocating files. 

By default, APL users create keyed files, that is, files whose individual records are 
identified by a one to 255 item character vector. However, file access within APL is 
not restricted to this file type. Indexed files (most commonly created by COBOL), 
relative files, i ndexed— re I at i ona I files, random files, unit record files, fixed 
files, and consecutive files are all accessible from APL. Each of these files have 
different capabilities (for more information see the CP-6 Host Monitor Services 
Reference Manual (CE74)), 



Table 12-1. File I/O Record Types 


Type 


Descr i pt i on 


1 


Component record. The record includes the APL datatype, 
rank, shape, date, time, account, user name and data 
in ravel order (default). 


2 


Datablock record. The record includes the APL datatype, rank, 
shape and data in ravel order. 


3 


Data record. Only the actual data is read or written. Reading 
always returns a character vector. 


4 


Record field description. If the file was created with a record 
field description, this is used to read or write the record. The 
data read or written is always a vector (possibly nested). 
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File Information Functions 



The functions in this group provide information about the files that are currently 
being accessed. 

UFNUMS Function (Numbers of Open Files) 

Syntax: 

R*^QFNUMS 

Descript ion: 

The UFtfUHS ni Iodic function returns an integer vector containing the stream numbers 
for the files currently open. 

Examples: 

UFtfUMS 
1 314159 

UFNAMS Function (Names of Open Files) 

Syntax: 

R'^UFNAMS 

Descript ion: 

The UFtfAMS ni Iodic function returns a character matrix showing the names of files 
current ly open. 

Example: 

UFNAMS 
*TEST 
TIMING 
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UFID Function , (File Identifier) 



Syntax: 

UFID Y 

Parameters: 

Y is a simple integer scalar indicating a file I/O stream that is currently open. 

Description: 

The UFID system function returns the CP-6 file identifier for the file I/O stream 
speci f ied. 

Examp I e : 

UFID 1 

*TEST 

UFID 3U159 
TIMIKGS.TESTAPL 

UFID" 1 31*159 
IcTEST TIHINGS.TESTAPL 

Opening, Closing, and Deleting Files 

The file functions in this group are used to initiate and terminate access to files. 

UFOPEN Function (Open File) 

Syntax: 

X UFOPEH T 

Parameters: 

T is a simple integer scalar indicating an available file I/O stream. 

X is a simple character vector indicating the name of the file to open or a vector 
of nested arrays containing a simple text vector indicating the name of the file to 
open, and optionally a file access matrix, a record field matrix, and a key 
definition matrix. 
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Descript ion: 

The UFOPEN system function is used to initiate file access through a stream. The 
left argument is the file identifier and the right argument is the stream number to 
be associated with this file. The number used for the stream number must be an 
integer and not currently in use as a stream number. 

If the left argument is a simple character vector containing a CP-6 file identifier, 
that file is opened for reading only. In order to create, update, or share a file, 
options are specified in the left argument following the FID and separated by commas. 
The options and their meanings ore provided in Table 12-2. 



Table 12-2. File Open Options 



Opt i on 



Mean i ng 



UPDATE 
♦ IN 
CREATE 

OLDFILE 
♦NEWFILE 
ERROR 

ALL 
*NONE 

SHARE IN 

CTG 

SCRATCH 
♦NAMED 

CONSEC 
♦KEYED 
RANDOM 
UR 

RELATIVE 
INDEXED 
CO 
IREL 

♦DIRECT 
SEQUEN 

LOAD 



COMP 

REASSIGN 



Opens file so records can be read and written. 
Opens file for reading only. 
Creates a file. 

For create, if file already exists use it. 

For create, even if file already exists create new file. 

For create, if file already exists report error. 

Share file (multiple updaters). 

If UPDATE, file open is for exclusive use. 

If IN, file open shares with other readers only. 

Only readers can shore file. 

For create, catalogues file in directory upon open. 

File is not permanent. 
File is permanent . 

For create, specifies organization of new file. 

For create, specifies organization of new file. 

For create, specifies organization of new file. 

For create, specifies orgonizotion of new file. 

For create, specifies organization of new file. 

For create, specifies organization of new file. 

For create, specifies organization of new file. 

For create, specifies organization of new file. 



For create of alternate index file, build indices 
on file c lose. 

CP— 6 file management will compress records. 
Uses IBEX ISET F$tie for additional options. 



♦denotes defaults 



If one of the option fields is not a valid option and is exactly two characters in 
length, it is used as the file type. Additional information on the meanings of these 
options can be found in the CP-6 Host Monitor Services Reference Manual (CE74) . 

The left argument of the UFOPEtf system function may also be a vector of nested arrays 
which permits the specification of file access controls, record-field definitions, 
and alternate key definitions. The topic named Specialized File Options (later in 
this section) contains information on this usage. 
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Examples: 

'TEMP' UFOPEN 1 

' COMMON .HIS ACCT , UPDATE .ALL' UFOPEtf 99 
APLSTUFF , DC , CREATE , ERROR , CTG • UFOPEN 1 23 
• DP^PACKZ/ • MYSTUFF , UPDATE • UFOPEN 3 U 1 5 926 



UFCLOSE Function (Closing and Renaming Files) 



Syntax: 

UFCLOSE TV 
FID UFCLOSE Y 



Parameters: 

TV is a simple integer vector indicating file I/O streams that are currently open. 

Y is a simple integer scalar indicating a file I/O stream that is currently open. 

FID is a simple character vector indicating the new name or new password by which 
this file will be known. 



Descr ipt ion: 

The UFCLOSE function closes the specified streams. For monadic UFCLOSE, the right 
argument is a scalar or vector of stream numbers. 

A file's name can be changed at closing time using dyadic UFCLOSE. The right argument 
is the stream number. The left argument is the new file identifier. 

Renaming a file requires DELF access in the file's access controls. The file's name, 
password, or both may be changed. The file's access controls (see File Access 
Controls) may also be modified at close time by specifying an access control matrix 
as the left argument. In general, the left argument to UFCLOSE may contain a fid, 
access control matrix or a nested vector containing both a fid and an access control 
matrix. 



Example: 

UFNUMS 
99 1234 31415926 

UFCLOSE 123* 99 

UFNUMS 
3U15926 
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UFERASE Function (Close and Delete File) 



Syntax: 

UFERASE TV 

Parameters: 

TV is a simple integer vector indicating file I/O streams that are currently open. 
Descri pt ion: 

The UFERASE function closes the specified streams and deletes the files that were 
opened to them. The right argument is a scalar or vector of stream numbers. Note 
that once a stream has been closed, referencing it before opening it once again will 
result in a FILE TIE ERR. 

Example: 

UFNUHS 
99 1234 31415926 

UFERASE 1234 

UFNUMS 
99 31415926 

UFCLEAR Function (Close All Open Files) 

Syntax: 

UFCLEAR 

Descr ipt ion: 

The UFCLEAR system function causes all currently open streams to be closed. It is 
functionally equivalent to the expression: 

UFCLOSE UFHUMS 
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Reading and Writing Records 



The functions in this group provide access to records within the file. Records may 
be accessed either sequentially or directly by specifying record number or key. The 
absence of the record number or key is used to indicate a sequential operation. 



UFAPPEND Function (Append Record to File) 



Syntax: 

R^X UFAPPENDR Y 



X UFAPPEND Y 



Parameters: 

X is the APL array that is to be written (appended) to the file. 

Y is a vector of up to 3 items. The first item must be a simple integer scalar 
indicating o file I/O stream that is currently open. The optional second item is a 
simple integer encryption seed (or a 4-element character vector). The optional third 
item is a simple integer scalar record type number as described in Table 12-1 (or a 
record field matrix). 

R is the key of the record that was appended. 



Description: 

The UFAPPEND function writes the data object to the file at the position of the lost 
record in the file plus the key interval of the file. The key interval can be set or 
obtained by using the UFKEYINT function. The key interval for files other than keyed 
files is always 1. The file must hove been open in UPDATE or CREATE mode. 

The right argument consists of the stream number, the optional encryption seed, and 
the optional type of record to be written. Only the stream number is required. If 
the encryption seed is 2ero or not present then the record will not be encrypted. If 
the third item of the right argument is omitted or 1, then an APL component record is 
written. If it is 2, then on APL datoblock is written. If It is 3, then the ravel 
of the data is written. Finally, if it is 4, the record field description associated 
with the file is used to format the record before writing. The left argument is any 
APL or ray. 

UFAPPENDR is identical in operation to UFAPPEND, and additionally returns the numeric 
key of the record written. 



Examples: 

*FAR OUT* UFAPPENDR 3 U 15926 

1 

* EXTERNAL RECORD TYPE' UFAPPEND 1 0 3 

* ENCRYPTED RECORD* UFAPPEND 1 998 
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UFREAD Function (Read a Record) 



Syntax: 



R*-UFREAD Y 



Parameters: 



Y 



is a vector of 1 to 4 items in length (stream, key, seed. type). 



R 



is the contents of the requested record. 



Descr i pt i on : 

The UFREAD function is used to read records. The right argument contains the stream 
number and optionally the record number or key, the encryption seed and the record 
type. If the key is a character vector, the argument must be a nested array with the 
key as the second item. If the key is an empty vector, then a sequential read is 
performed. If a record with the specified key does not exist or if a sequential read 
reaches the end of the file, FILE IlfDEX ERR is reported. 

As in UFAPPEHD , the encryption seed can be non-zero to request encryption and record 
types 1 (the default). 2. 3. or 4 may be requested. The result is the record with 
the specified key or the next sequential record if READ access permission has been 
granted . 

Reading when a record type of 3 is specified always results in a character vector 
resul t . 



UFREAD 3 U 15926 1 
FAR OUT 

UFREAD 12 0 3 
EXTERNAL RECORD TYPE 

UFREAD 1 3 998 
ENCRYPTED RECORD 

UFREAD 1 'TEXTKEY* 
RECORD WITH TEXT KEY 



Reading Sequentially 

A sequential read may be performed by not specifying a key. For example: 



where 5 is the stream number in this case. In order to read o non-APL file 
sequentially the following expression is used: 

UFREAD 9 0 3 

where 9 is the stream number in this example. 



Examp I es : 



UFREAD 5 
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UFWRITE Function (Write or Replace a Record) 



Syntax: 

X UFVRITE Y 

Parameters: 

Y is a vector of 1 to 4 items in length (streom, key, seed, type). 
X is the APL array that is to be written to the file. 

Oescr Ipt ion: 

The UFVRITE system function couses a record to be written (new or replaced) in the 
file with the specified key. 

The right argument contains the stream number and optionally a record number or key, 
an encryption seed and a record type. 

If the record identifier is a character key, the right argument must be o nested 
array with the key as the second item. If the key is not specified and this is not 
an indexed or irel file, then the record last read by this stream is replaced. 

A non-zero value for the encryption seed will cause the record to be encrypted before 
writing it. The same encryption key must be used to subsequently read it. 

The record type is 1 for a component record, 2 for a datablock record, 3 for an 
external record, and 4 for the file's record field definition. 

The file must hove been opened with either the UPDATE or CREATE options and WNEW or 
UPDATE permission must be granted. 

Exomp I es : 

'REPLACEMENT' UFWRITE 31415926 1 

'TEXT KEY' UFWRITE 1 'OJ SIMPSOM' 27165 

'EXTERNAL WRITE' UFWRITE 1 3330 0 3 

UFDROP Function (Delete Record from File) 

Syntax: 

UFDROP Y 

Parameters: 

Y is a vector of length 2 (stream, key). 
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Descri pt ion: 

The UFDROP system function deletes specific records from o file. The right argument 
identifies the stream and the record number or key of the record to delete. 



Exompl es : 

UFDROP 1 2 

deletes record number 2. The file must be opened in either UPDATE or CREATE mode to 
use this function and OELR access permission must be granted. 



UFRDCI Function (Return Component Information) 



Syntax: 

R*€FRDCI Y 



Parameters : 

Y is a 1, 2, or 3 item vector (stream, key, seed). 
R is a simple character vector of length 36. 



Descript ion: 

The UFRDCI function returns a character vector of 36 items containing the date in the 
format TfUMDD (e.g., 841030) in the first six items, the time in the format HHMMSSSS 
(e.g., 12300000 for 12:30 PM) after the blank following the date. The remaining 
characters are the account and user name fields (see Figure 12-1). 

The right argument is the same as for UFREAD except that the record type is not 
specified (this function only works on component records). 

If the record was not written as a component record, then the error NOT AN APL FILE 
is reported. For example: 

UFRDCI 1 2 
840922 \Qi\\^%\^HAGAPL 201G0NE 



Fi le Access Controls 



The functions in this group set and retrieve the current file access controls for 
files that are currently open. Access controls may also be set when the file is 
created by the UFOPEN system function, or modified when closing the file by the 
\^CLOSE system function. 
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File Access Mat r i x 



An APL file access matrix is used to indicate the file access controls. Access 
controls permit or prevent access to files by users. Permissions are indicated in 
terms of accounts (which may be wild— carded) and file access permissions granted to 
those accounts. Table 12-3 contains the file access permissions which are available. 

An APL file access matrix is a simple N— by— 17 character matrix. The first eight 
columns contain on account identifier. The ninth column must always be blank. The 
remaining columns contain either the character 'Y' to permit the corresponding access 
or the character 'N' to restrict the access. 



ExampI e : 

AC* I 17p(8t'905ilPL'),' YYYYNNNN' 
BC^l np{8*'TEST?n\' YHYHHNNN' 
CC*AC,IUI0]BC 



In the example, AC is a file access matrix which permits the account 905APL to read, 
delete, update, write new records and see the file name in the file directory (or 
account) . 

The file access matrix BC permits any account beginning with the characters *TEST* to 
read, write new records, and see the file name in the file directory. 

The file access matrix CC provides the permissions associated with AC and BC to their 
respective accounts. 



Table 12-3. CP-6 APL File Access Permissions 


Co 1 umn 


Permission 


Description 


10 


READ 


can use UFREAD, UFRDCI, UFRDAC , QFEMQ, QFDEQ 


11 


DELR 


can use UFDROP to delete records 


12 


WNEW 


can use QFAPPEND, \yWRITE to write new records 


13 


UPDATE 


con use UFVRITE to replace records 


14 


DELF 


can use QFSTAC , UFERASE or dyadic UFCLOSE 


15 


NOLIST 


can use UFLIB will not list file name 


16 


REATTR 


can use UFSTAC 


17 


EXEC 


not meaningful to APL files 



UFRDAC Function (Return File Access Matrix) 



Syntax: 

R*UFRDAC Y 
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Parameters: 

Y is a simple integer scalar indicating a file I/O stream that is open. 
R is a simple character matrix of shape N-by-17. 



Descript ion: 

The UFRDAC function returns the APL file access matrix for the specified file. Each 
row of the matrix contains an account identifier (which con be wild-corded) and the 
corresponding file permissions. The right argument is a stream number. If the file 
was opened with the create option, then it must also have been opened with the CTG 
opt I on. 



Examples: 

UFRDAC 1 
? HNNNNHN 



UFSTAC Function (Store File Access Controls) 



Syntax: 

H UFSTAC Y 



Parameters: 

Y is a simple integer scalar indicating a file I/O stream that is open. 

M is a file access matrix, that is. a simple character matrix of shape N-by— 17. 



Descript ion: 

When the UFSTAC function is executed, the file opened to stream Y has its access 
controls revised to reflect the permissions specified in M. The right argument is the 
stream number of a currently open file. The left argument is a file access matrix. 



Examples: 

(((9*ACC0UNT) ,'YYHNNHYN' ) Ai'iUFRDAC DUFSTAC I 

This example will allow the account named in the variable ACCOUNT to read and delete 
records and to change the access permissions of the file. 
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Coordinating Shared Fiies 



The functions in this group ore intended to be used when more than one user is 
accessing a file, and it is being updated by at least one user. The enqueuing 
protocol should be agreed upon for all applications using the file; its use is not 
enforced by the system. 

UFENQ Function (Hold a Record) 

Syntax: 

R*-UFElfQ Y 

Porameters: 

Y is o vector of length 2 (stream, key). 

Descr i pt i on : 

After the UFElfQ function has executed, another user executing QFENQ on the same file 
and resource name will be halted until the user currently holding the resource 
releases it with the UEDEQ function. 

The right argument contains the tie number and resource name. The resource name is 
an integer or character value, most commonly a record key. 

UFDEQ Function (Release Record or File) 

Syntax: 

R^UEDEQ Y 

Parameters: 

Y is a vector of length 2 (stream, key). 
Descript ion: 

When the UFDEQ function is executed, the resource specified is released permitting 
another user currently waiting for this resource to continue. 

The right argument contains the tie number and optional resource name. 

If the resource is not specified, then all resources currently held by this user are 
released for this file. 
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File Status Functions 



The following functions give additional information about a specific currently open 
file. 

UFRKEY Function (Return Key Values) 



R*-UFRKEY YS 



Parameters: 

YS is a vector of length 2 or 3 (stream, keytype, altkey). 
R is the key. 



Descri pt ion: 

The UFRKEY function returns specific key volues depending upon the second item in YS . 
If rS[2] is 1, UFRKEY returns the key of the first record in this file. If YS12] is 

2, UFRKEY returns the key of the record most recently read or written. If YS[2], is 

3. UFRKEY returns the key of the last record in the file. If YSIZ] , is 0. UFRKEY 
returns the key of the record lost accessed when reading or writing on the specified 
key index. (For non-IREL files, the difference between 0 and 2 is that file position 
is maintained independently for every key index and 2 is the key contained in the 
most recently read or written record. 0 indicates the position at which a sequential 
read along a particular key index would commence; for IREL files they are 
equivalent). 

The right argument is a simple integer vector of two or three items. The first item 
is the stream number and the second item is the integer 0, 1 , 2 or 3. The third 
(optional) item is the key index. If the third item is not present, 1 (primary key) 
is assumed. The key index is not 0/0 dependent. 

If the file is currently empty, on empty vector is returned. 

For keyed files, a key length of three characters is treated as a numeric key, for 
all other key lengths the keys are returned as a character vector. 



FL I M-*- (UFRKEY 1 I) .UFRKEY 1 3 

If this is a keyed file with numeric keys or any other file type other than INDEXED 
or IREL, then this expression results in FLIM being assigned on integer vector of 
length 2. The first item of FLIM is the record number of the first record in the 
file, the second item is the record number of the last record in the file. For 
example: 



Syntax: 



ExampI es: 



UFRKEY I 



I 



0 UFRKEY 1 2 0 UFRKEY 1 3 



20 
60 
98 



qU*-UFRKEY 
SAN FRANCISCO 
20 



2 2 fl CURRENT KEY ON SECOND KEY INDEX 
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UFSIZE Function (File Size) 



Syntax: 

R^UFSIZE Y 

Parameters: 

Y is o simple integer scalar indicating a file I/O stream that is open. 

Descript ion: 

The UfSlZE function returns the number of bytes of storage allocated to the file 
opened to stream Y. 

UFKEYINT Function (Set Key Interval) 

Syntax : 

R*-nFKEYItfT YS 

Parameters: 

YS is a simple 1 or 2 element integer vector. 

Descr i pt i on : 

The UFKEYIlfT function sets the increment to be used when appending a record to a 
keyed file. The right argument is a stream number and an optional integer value. 

The result is the previous increment or the current increment depending on whether 
the current increment hos been replaced. The defoult value (after UFOPEN) is 1000 
for keyed f i les. 

UFKEYS Function (Return File Keys) 

Syntax: 

R*-UFKEYS Y 

Parameters: 

Y is a simple integer scalar indicating a file I/O stream that is open. 
R is o key definition matrix. 
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Descr ipt ion: 

The UFKEYS system function returns the key list for the specified stream. 

For INDEXED files, this is a matrix of shape N-by-3 containing the starting position, 
length, and duplicate indicator. The first column contains the index in character 
positions of the first character of the key (the first index position is Q/O). The 
second column contains the length in characters of the key. The third column 
contains 1 if the key must be unique or 0 if the duplicate key values are permitted. 
Each row defines a key, the first row is the primary key (this key must always be 
unique). Any subsequent rows are alternate keys (may be unique). 

For IREL files, this is a matrix of shape N-by-2 containing field numbers in the 
first column and key unique/key-end flags in the second column. The second column 
values and their associated meanings are as follows: 0. a non— unique key; 1, a unique 
key; 2, the last field of a non-unique key; and 3, the last field of a unique key. 

For other file types, the result is: 

1 3p 0 0 1 



Example: 

An example of UFKEYS with an indexed file is: 

UFKEYS k 
10 H 1 
14 20 0 
1 5 0 

In this example, the file open to stream 4 has 3 keys. The primary key is 4 
characters long beginning at position 10. The secondary keys are 20 and 5 characters 
long and begin at positions 14 and 1 respectively. Only key values for the primary 
key must be unique. 

An example of UFKEYS with an IREL file is 
UFKEYS 9 

3 3 
5 0 

4 2 

8 1 

9 3 

In this example, the file open to stream 9 has 3 keys. The primary key is field 3. 
The first alternate key is field 5 followed by field 4. The first alternate keys do 
not have to be unique. The last alternate key is field 8 followed by field 9. The 
last key values must be unique. 



UFCRPT Function (Set File Encryption Seed) 



Syntax: 

X UFCRPT Y 
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Parameters: 

Y Is a simple integer scalar indicating a file I/O stream that is open. 
X is a simple integer scalar encryption seed. 



Descript ion: 

The UFCRPT function changes the seed that is used by default for subsequent read and 
write operations to this stream. The initio! default encryption seed is zero when a 
stream is opened. The right argument is the stream number. The left argument is an 
encryption seed. 

A seed can be specified on the UFREAD, UFWRITE, QFAPPEND and UPRDCI functions which 
overrides this default seed. There is no explicit result to this function. 



Library or Account Information 

The functions in this group return information about the files in an account. 



UFMA Function (Return File Management Account) 



Syntax: 

R*-nFMA 



Descri pt ion: 

The UFMA system function returns a character vector of length 8 containing the 
current default file management account which is used whenever o file identification 
does not contain an account identifier. This would typically be the same as the 
current logon account but can be changed by a )IDIR command (for example). 



UFLIB Function (Return File Names) 



Syntax: 

R*^LIB A 
R^X UFLIB A 

Parameters: 

A is a simple character vector containing an account or a wild— carded file name 
and account . 

R is a simple character matrix of shape N-by— 40. 

X is a simple character vector of length 2 or a simple character matrix of shape 
H-by-2. 
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Descr i pt ion: 

The UFLIB function returns a character matrix of shape N-by--40 containing names of 
the files in the specified account. If a wild-carded file name is specified, the 
result includes only those names which contain all of the characters in the wild-card 
with any characters (zero or more) in place of the '?' character. 

The right argument is either a CP-6 account identifier or a wild-corded file 
ident i f ier . 

An account name is 0 to 8 characters in length. A wild-carded file identifier is 1 
to 31 characters in length containing a single character and any other 
characters, followed by a period, and an (optional) account name. 

Monodicclly, the result is a charocter matrix of shape N-by-40 where each row 
contains the account in the first 8 characters (or blanks for the default file 
management account), a blank, and the file name left justified in the remaining 31 
characters. 

Dyadical ly, only those files which have a file type listed in the left argument are 
returned. If the left argument is empty (a 0— by— 2 matrix), all file types are 
selected. Note that dyadical ly, UFLIB returns a CP-6 FID which can be used directly 
by the UFOPEff system function. 

Examples: 

UFLIB 'TESTAPL' 
TESTAPL '.APLPCF 
TEST API : MA ILJCENTRAL 
TESTAPL IDSWS 
TESTAPL GRAFX 
TESTAPL TESTUS 

UFLIB TESTAPL* 
TESTAPL -.APLPCF 
TESTAPL tMAILjCEHTRAL 

UFLIB *?WS. TESTAPL' 
TESTAPL IDSUS 
TESTAPL TESTWS 

UFLIB •*•?.' 
*A 

*S 

'WA' UFLIB 'TESTAPL' a WORKSPACES. 
IDSWS. TESTAPL 
TESTWS. TESTAPL 

"UFLIB 'TESTAPL' a ALL FILES. ( 

-.APLPCF. TESTAPL 

: MA ILJCENTRAL . TESTAPL 

IDSWS . TESTAPL 
GRAFX. TESTAPL 
TESTWS .TESTAPL 

Possible Errors: 

A RAHK ERR is reported if: 

o ^ is not a scalar or vector. 

A DOMAIN ERR is reported if: 

o A \a not simple or contains an item that is not a character. 

o ^ is not a wild-carded file name containing a legal CP-6 account. 



CE38-04 



UFLIB 

Function (Return File Names) 



12-19 



o The account name is longer than 8 characters. 



Record Field Descriptions 



When a file is created, a record field matrix may be specified. This matrix defines 
the contents of the records in a file in terms of fields. Each field (or row of the 
record field matrix) defines the datatype, location within the record and the field 
s i ze . 

A record field matrix is c simple integer matrix of shape N-by-4 or N-by-5. The 
record field matrix column numbers (in origin 1) and their definitions are: 

1. Datatype. This is an integer indicating the type of data which is in this field. 
Table 12-4 contains the numbers of the valid datatypes. 

2. Length. For decimal fields, this is the number of digits (minus possible 
overhead); for floating point and character fields, this is the number of bytes; 
for integer fields, this is the number of bits. Table 12-4 indicates the rules 
for the field lengths. 

3. Scale. A scale volue may be specified for some decimal datatypes. The scale 
value must be in the range -32 to 31 and it indicates the number of digits after 
the decimal point. Table 12-4 indicates whether the scale is permitted for each 
datatype. 

4. Vector. Numeric fields may be vectors of numbers. A vector value of 0 indicates 
that this field is a scalar. A negative vector value indicates a fixed length 
vector whose length is the absolute value. A vector value greater than zero 
indicates the field number whose value indicates the length of the vector. 

5. Logical Order. This optional value may be used to reorder the physical record 
contents into a logical order. If all logical order values are 0, then the 
physical order of fields directly corresponds to the logical order. Otherwise, 
the logical record corresponds to those fields whose logical order is greater 
than 0 sorted by increasing logical order number. Logical order values ore only 
used to communicate with other CP-6 processors. 

The physical order of fields in a record is always the order in which the fields 
ore defined. That is, the first physical field is the first row of the record 
field matrix. 

When accessing records in a file, the use of the file's record field matrix may be 
requested by specifying a record type 4. In this case, APL will automatically 
perform datatype conversions between the internal APL datatypes and those in the 
record field matrix datatypes. 

When reading records using a record field matrix, the result is a vector with as many 
items OS the record contained (usually the number of fields defined). A DOMAIN ERR 
is reported if the contents of a field are not legal for the datatype indicated by 
the record field matrix. This occurs if a decimal field (for example) contains a ':' 
character in a digit position. 

When writing records using the record field matrix, the value to write must be a 
vector that is not longer than the number of fields (rows) in the record field 
matrix. A DOMAIN ERR is reported if: 

o o numeric item to be written has a character datatype in the corresponding row of 
the record field matrix. 

o a character item to be written has a numeric datatype in the corresponding row of 
the record field matrix. 

o the value overflows (or underflows) when converted to the type in the 
corresponding row of the record field matrix. 

When creating a file with a record field matrix, the matrix is specified as on item 
of the left argument of the [ITOPEN system function. During the execution of the 
UFOPEN function, the system verifies the contents of the record field matrix and 
reports any inconsistencies as a DOMAIN ERR or a FILE I/O ERR. 
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Table 12-4. Record Field Datatypes and Rules 



Datatype 


Type 


Dec i ma 1 


Size 


Sea 1 e 


Digi ts 


Overhead 


Undef i ned 


0 




3 




0 


0 


Integer 


1 




1 




1 


1 


Single Floating 


3 




3 




1 


2 


Double Floating 


4 




3 




1 


2 


Packed decimal leading sign 


9 


YES 


2 


YES 


2 


1 


Floating packed decimal 


10 


YES 


2 




2 


3 


Fixed length character 


21 




3 




0 


0 


Varying length character 


22 




3 




0 


0 


Unsigned integer 


24 




1 




1 


0 


Packed decimal trailing sign 


25 


YES 


2 


YES 


2 


1 


Packed decimal EBCDIC sign 


31 


YES 


2 


YES 


2 


1 


Packed decimal unsigned 


40 


YES 


2 


YES 


2 


0 


Decimal unsigned 


41 


YES 


3 


YES 


3 


0 


Decimal leading sign 


42 


YES 


3 


YES 


3 


1 


Decimal trailing sign 


43 


YES 


3 


YES 


3 


1 


Leading overpunch sign 


44 


YES 


3 


YES 


3 


0 


Trailing overpunch sign 


45 


YES 


3 


YES 


3 


0 


Floating decimal 


50 


YES 


3 




3 


3 


Packed decimal leading EBCDIC 


51 


YES 


2 


YES 


2 


1 


Date 


54 


YES 


2 




4 


1 


UTS 


55 




1 




5 


0 


TEXTH 


56 




3 




0 


0 


Time 


57 


YES 


2 




4 


1 



where 

Size rules: 

1. The field can be of any length up to 36 bits starting at any bit. 

2. The field length is in nibbles and starts on a nibble or character boundary. 

3. The field length is in characters and starts on a character boundary. 
Digits Rules: 

The number of decimal digits in the field is: 

0. none 

1. 1092*SIZE-OVERHEAD 

2. {1{SIZE+ISIZE^9)^5)-0VERHEAD 

3. i(.SIZE^9)-0VERHEAD 

4. Length must be 16 ^nibbles). 

5. Length must be 36 (bits). 

Note: Decimal fields cannot contain more than 63 digits. 
Overhead Rules: 

0. 0 (none) 

1. 1 (bits for integer, digits for decimal) 

2. 9 (bits) 

3. 2 3ta/0+rrPr=10] (digits) 
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UFFLDS Function (Return Record Fields) 



Syntax: 

R*{]FFLDS Y 



Parameters: 

r is a simple integer scalar indicating a file I/O stream that is open. 



Description: 

The UFFLDS system function returns the record field description for the specified 
file. The result is an Integer matrix of shape (A^,5). If the file tied to the 
specified stream has no record field list defined, the result is a matrix of shape (0 
5). 



ExampI e : 

UFFLDS 29 
1 36 0 0 0 

21 12 0 0 0 
10 12 0 0 0 

6 2 0 0 
50 32 0 0 0 

22 0 0 0 0 

In this example, file stream 29 is open to a file whose records contain 6 fields. 
The field numbers and their corresponding types are: 

1. Integer. Values in the range C2*35) to ("1+2*35). 

2. Text vector. 12 characters in length. 

3. Floating packed decimal. 9 decimal digits in the range ~1£'136 to 1£'136 
exclusive. The smallest non-zero numbers In magnitude ore ~1£'~128 and 1£'~128. 

4. Leading overpunched signed decimal. 6 decimal digits (2 after the decimal 
point). The largest values are 9999.99 and ~9999.99. 

5. Floating decimal. 30 decimal digits in the range 'IflS? to 1£'157 (exclusive). 
Note that APL will provide an approximation to these values accurate to the 18 
most significant digits. 

6. Variable length text vector. The maximum length of this field is 511 characters. 



The following examples demonstrate writing records to this file using API's automatic 
data conversion capability (record type 4). 

X^IZ^ 'CHARilZ)' (*l) 12.3*5 (01) 'VARYING* 

X UFWRITE 29 1 0 4 
X 

123 CHARnZ) 2.718281828 12.345 3.U1582654 VARYING 

In the above example, X is written to the file, APL will pad field 2 with blanks to 
fill it out to 12 characters in length. The value written for fields 3 and 4 wi I I be 
rounded to the number of digits defined for the field. 

UFREAD 29 1 0 <i 
123 CHARilZ) 2.71828 12.35 3.14159265<( VARYING 

Notice that field 2 has been padded with blanks and that field 4 has been rounded to 
2 digits after the decimal point. 
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Alternate Indexed Files 



The following file I/O functions permit the specification of on alternate index: 
UFREAD, UFRDCI QFDROP, UFRKEY. The alternate key list can be obtained via the UFKEYS 
function. 

An alternate key is specified as a nested 2-item argument in the position in which 
the key is found. The first item is the key index number. The second item is the 
key value. An empty vector for the key value causes a sequential read along the 
specified alternate key to occur. For example: 

UFREAD 9 (3 {'SMITH')) 0 3 

In this example, stream 9 is read. The third key is searched for the value 'SMITH' 
(trailing blanks ore supplied by APL if the key is shorter than the key length). If 
multiple records with that key exist, the first record with that key is returned. 
Subsequent reads on this stream that do not specify a key index or specify index 0 
will use the third key index. 

In the following example, all records with the value 'MARTIH' for the third key index 
are removed from the file: 

UFDROP 9 (3 'MARTIN') 

If only one particular 'MARTIN' record is to be deleted, the key value for a unique 
key (there is always one) must be provided. 

For IREL files, the key index must always be provided and the key value must be a 
vector of field values. For example: 

UFREAD k (2 (.5)) 0 4 

In this example, the second key index is used. The key value that will be found is 
5. 



Specialized File Options 

The left argument of the UFOPEN and UFCLOSE system functions can be: 

o a simple character vector containing the CP-6 file identifier and options, 

o a vector of arrays, where each item In the vector can be: a character vector 
with the CP-6 fid, an access control matrix as described in ^RDAC , a record 
field matrix, or on indexed key list as described in UFKEYS. The access control 
matrix and Indexed key list are only used for CREATE opens. If OLDFILE is 
specified and the file exists, the access controls and index keys ore not used. 
The character vector contolning the file identifier must appear before the 
alternate keys in the list of items. 



Examp I es : 

To create a file which permits any CP-6 user to read with a 5 character primary key 
starting at Index 1, a 4 character alternate key starting at index position 6, a 20 
character alternate key starting at Index position 10, and another 20 character 
alternate key starting at Index position 30, the following is entered: 

ALTKEYS^k 3p 1 5 I 6 4 0 10 200 30 20 0 
AC^l np' (9i'?' ) ,'Y' ,7p'N' 

FID*- ' ALTFILE , CREATE , NEWFILE , INDEXED ,LOAD, CTG ' 
(FID ALTKEYS AOUFOPEN 1 
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UFKEYS 1 

1 5 I 

6 4 0 
10 20 0 
30 20 0 

UFRDAC 1 
? YNNNNNHN 

All of the options available through the IBEX !SET command are also available to 
users wishing to open a file. For information on the SET command, see the CP-6 
Programmers Reference Manual (CE40) . 

To create an INDEXED file in APL with the name INDEX01 and with the key starting in 
the 73rd character and being 8 characters in length, the following APL expressions 
can be used: 

snSET F%2i INDEXQl,KEYX'=72,KEYL=B' 

' .REASSIGN, INDEXED, CREATE, NEWFILE' UFOPEH 31 

The options that APL permits on the UFOPEH all have defaults that will override the 
SET options. That is, the SET options EXIST=, SHARE=, FUN=, ORG= and ACS= will be 
ignored on the )SET command and so they must be specified on the UFOPEN if different 
from APL's default options. 



Possible Errors: 

A RANK ERR is reported if: 

o the left argument of UFOPEN or QFCLOSE is not a scalar or vector. 
A LENGTH ERR is reported if: 

o the left argument is not simple and it contains zero or more than four items. 
A RANK ERR is reported if: 

o any item of the left argument is not a scalar, vector or matrix. 
A DOMAIN ERR is reported if: 

o any item of the left argument is not simple. 
A LENGTH ERR is reported if: 

o a matrix item of the left argument is not of shape N-by— 17 (access control 
matrix), or on N-by-3 (alternate key matrix) matrix. 
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Section 13 

CP-6 APL I-D-S/II System Functions 



CP-6 APL contains system functions which provide access to I-D-S/II databases. All 
of the COBOL language DML (Data Manipulation Language) statements have equivalent APL 
functions. In addition to these standard DML functions, the APL interface contains a 
number of unique functions which may be used to obtain detailed information about the 
database being accessed. 

In order to make use of this facility an APL subschema must be generated. The 
creation of I-D-S/II databases and subschema generation is achieved through the 
execution of various I-D-S/II utility programs. 

R*UDBSUB ' sub-schema-name , pr i vacy-l ock , SHARE' 

This function must always be the first I-D— S/II function to be executed during an APL 
session. It informs I-D-S/II of the name of the subschema to be used and the result 
of its execution is the name of the associated schema. If the subschema, schema or 
areas reside in on account other than the current file management account, or if 
their file management name is different than their schema name or the CP-6 file 
containing the subschema is passworded, a )SET command is required to direct I— [)-S/II 
to the correct file. For example, if the subschema name is SSCHFILE and it resides 
in the file: SSCHFILE_TAA22TEST , the schema file name is SCHFILE and it resides in 
the file SCHFILE . 123APL .PSSWD and the area to be used in this subschema is AREAO in 
the CP-6 file M AG ARE A. 122 F DS . The )SET commands required to use this database in APL 
are: 

)SET SSCHFILE SSCHFILE_7A A23TEST 
)SET SCHFILE SCHFILE . 122APL .PSSWD 
)SET AREAO MAGAREA . 123 IDS 

The optional positional parameter SHARE when present causes all of the items in the 
database to become automatically shared between'^the user work area and the APL 
workspace. This allows the functions UDBFROM and UDBTO to be performed automatically 
upon assignment or a reference to a workspace variable with the same name as the 
corresponding database item. Note however, item names containing underscores will 
appear in the workspace with deltas replacing the underscores. 

The following errors are possible when executing the UDBSUB system function: 

I-D-S/II LIBRARY HOT AVAILABLE 

The alternate shared library named I-D-S/II either does not exist or another 
alternate library is currently associated. This error may be sidetracked as error 
number 201 . 

INVALID SUBSCHEMA 

The file indicated as the subschema is not an I-D-S/II subschema file. This error 
may be sidetracked as error number 202. 

FILE TBL FULL 

The maximum number of files that an APL user may open ore currently open. In order 

to use I-D-S/II, some files must be closed. This may be sidetracked as error number 
203. 

SUBSCHEMA NAME ERR 

Either the subschema name and privacy key is ill-formed or the subschema name in the 

file does not match the name supplied. This may be sidetracked as error number 205. 



CE38-e4 



CP-6 APL I-D-S/II System Functions 



13-1 



SUBSCHEMA ACCESS ERR 



Access to the subschema has been denied because the file does not exist, it is 
passworded, or the privacy locl<s do not match. This may be sidetracked as error 
number 206. 



Subschema Information Functions 



The following functions give information about subschema names and subschema name 
types. 



UDBNAMES Function (List Subschema Names) 



Syntax: 

R^UDBNAHES 



Descr i pt ion: 

The UDBNAMES ni Iodic system function returns the names of all of the realms, sets, 
records, items, and I-[>-S/II keywords available through the current subschema. The 
shape of the result is N by M where N is the number of names and M is the length of 
the longest name. 



UDBTYPES Function (Subschema Name Types) 



Syntax: 

R*-UDBTYPES 



Descript ion: 

The UDBTYPES ni Iodic system function returns a numeric array of shape N-by-6 
indicating the attributes of each corresponding name in UDBNAMES. The first item of 
each row indicates the type of object represented by that name. The second item of 
each row contains usage or mode information, the third item of each row contains 
encoded flogs that are type specific, the fourth item of each row contains the index 
in UDBNAMES of the object that owns this object, the fifth item of each row contains 
sub-type information and the sixth item of each row contains the length or the 
object's order. 

Column one contains: 

OBJECT TYPE 

1 REALM 

2 RECORD 

3 FIELD 

4 SET 

5 PARAMETER 

6 unused 

7 I-D-S/II KEYWORD 

8 Record Key 
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Record Type Information 

For records, column two contains the location mode for this record: 

e DIRECT 

1 CALC 

2 VIA SET 

3 SEQUENTIAL 

4 INDEXED 

Column three contains flags decoded as: 
where (in index origin 1): 

R 
R 
R 
R 
R 
R 
R 
R 
R 
R 
R 
R 



1, name is in SUBSCHEMA 

'2[ name understood by I— D-S/II 

'3' STORE is ol lowed 

'4" MODIFY Is a! lowed 

[5] DELETE is a! lowed 

6] ERASE is a I lowed 

7^ variable length 

'&[ in mul t ipie areas 

|9J has alternate keys 

IOI on elementary item 

Item is signed 

'12' item is scaled 



Field Type Information 

The second column for fields contains usage information. The range of possible 
values are: 

0 DATA ITEM 

1 DATA BASE PARAMETER 

2 LOCATION MODE DIRECT FIELD 

3 AREA-ID FIELD 

4 CALC KEY SYNONYM FIELD 

5 SCAN KEY SYNONYM FIELD 

The third column for fields contains flags that may be decoded with the expression: 
f <■ ( 35p2 ) rUDBTYPES [F;3] 

where the meanings are the same as for the record flogs. 

The fourth column contains the record number in UDBNAHES that this field belongs to. 
The fifth column contains the data type of this field. Values ore: 

0 CHARACTER 

1 INTEGER DB KEY 

2 INTEGER 

13 SINGLE PRECISION FLOATING POINT 

14 DOUBLE PRECISION FLOATING POINT 

The sixth column is used for character data items to indicate the length of the 
string. 



CE38-04 



DDBTYPES 
Function (Subschema Nome Types) 



13-3 



Set Type Information 



The second column for sets indicates the mode of this set. Valid values of mode are: 

0 CHAIN 

1 RECORD ARRAY 

2 POINTER ARRAY 

The fourth column for sets indicates the index in UDBNAHES of the record that owns 
this set. The fifth column indicates the type of set this is. Values of set type 
are: 

0 USER SET 

1 CALC SET 

2 PRIMARY KEY 

3 SECONDARY KEY 

The sixth column indicates how this set is ordered. Values of order ore: 

0 FIRST 

1 LAST 

2 NEXT 

3 PRIOR 

4 SORTED BY KEY 

Parameter Type Information 

Column four contains the index in UDBNAMES of the record related to this database 
parameter . 



I-D-S/II Function Arguments 

In the following description of the APL language interface to I-D-S/II, the functions 
are described In terms of the database objects known to I— D— S/II. The database 
objects are Indicated in APL by either the text of the object's name or by the 
numeric Index of the object's name in UDBNAMES. 

A series of database objects and keyword names moy be indicated by separating the 
names by blanks in a character vector, as an Integer vector of object indices (in 
UDBNAMES) , or as a series of object values (Including character and/or numeric 
indices), separated by semi— colons and enclosed in parentheses as in arguments to 
UFMT . This means that all of the following I-D-S/II calls are equivalent: 

R<-UDBFIND 'STUREC WITHIH COURSET CURREHT STUNAHE' 
Rt-UDBFItfD { 'STUREC ; *UITHIN' ; 'COURSET' CURRENT* ; 'STUNAME* ) 
R*-QDBFIND i'STUREC WITHIN COURSET CURRENT' ;* STUNAME' ) 
R*-UDBFIND (5 *2 3 3k -.'STUNAHE') 

where in the last example, the fifth row of WBNAMES contains the text STUREC, the 
42nd row contains WITHIN, etc. 
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Name and Set Information 

The following functions give information about subschema names and sets. 
UDBANLZ Function (Analyze Subschema Names) 

Syntax: 

R*-DDBANLZ A 

Descr i pt i on: 

The right argument to this function is a simple character vector containing subschema 
names and keywords. The result is an integer vector containing the index in UDBNAMES 
of each name in A. 

UDBOWNER Function (Set Owner) 

Syntax: 

R*-UDBOWHER B 

Parameters: 

B is a character vector containing the name of a set or record. Optionally, it 
may be the index in DDBNAMES of the name of a set or record. 

Descr ipt ion: 

The right argument to this function is either the name of a set or record. The 
result for a set is the index of the record that owns this set in UDBNAMES. The 
result for a record is a vector of the indices of the sets that this record may own. 

UDBMEMBER Function (Set Member) 

Syntax: 

R^UDBHEHBER B 

Parameters: 

B is a character vector containing the name of a set or record. Optionally, it 
may be the index in UDBNAMES of the name of a set or record. 
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Descr i pt ion: 

The right argument to this function is either the name of a set or record. The 
result is always an N-by-3 matrix indicating in column one the sets or records that 
the supplied record or set may be a member of. The second column contains zero if 
membership is manual or one if membership is automatic. The third column is zero if 
membership is optional or one if membership is mandatory. 



UDBINFORM Function (Database Register) 



Syntax: 

R*-UDB INFORM B 



Parameters: 

B is a simple character vector. 



Descr i pt ion: 

The UDBINFORM function returns the contents of the specified database register. The 
registername is specified as one of the following: 

DBSTATUS 

DBREALM 

DBSET 

DBRECORD 

DBPRIVACY 

DBDATANAME 

DBKEYNAME 

DIRECTREFERENCE 



Accessing Data 



The values of record items may be set and obtained by either sharing variables in the 
workspace with I-D-S/II or by the functions [IWBFORM and UDBTO. Sharing of all 
database items may be requested when the database is opened (see UDBSUB) or by using 
the Shared Variable system functions. For example, if USERNAME is the name of on 
item in the database then the expression: 

'IDS. '.SYS' USVO 'USERNAME' 

2 

returns 2 indicating that the variable USERNAME in the active workspace may be 
referenced or assigned is a surrogate for the value in the UWA. Note that erasing 
USERNAME or retracting USERNAME by the USVR system function will discontinue sharing. 
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UDBFROM Function (Retrieving Data) 



Syntax: 

R*-UDBFROM B 



Descript ion: 

The UDBFROM function returns the values of the specified items in the UWA (User Work 
Area). The items in the itemlist must all be of type numeric or all character or a 
DOMAIN ERR will occur. Character values in the result ore separated by carriage 
return characters. 

->>•. 

UDBTO Function (Storing Data) 



Syntax: 

R*-UDBTO (item I ist;valuel ist[:valuel ist; . . .]) 



Parameters: 

itemlist is a simple character vector containing the names of I-D-S/II items. 

Optionally, this may be a simple integer vector containing the indices of items in 

UDBHAMES . 

valuelist are simple scalar numbers or vectors of numbers to be assigned to the 
corresponding item named in itemlist. Character values ore included as separate 
i terns i n the list. 



Descript ion: 

The right argument to this monadic system function is a list, the first item of which 
is either the character vector of the itemnames or a numeric vector of the name 
indices in UDBNAMES. The remaining items in the argument list consist of the values 
to be moved into the UWA for each corresponding item name. A valuelist consists of 
character or numeric scoiars or vectors. If a character vector is supplied, separate 
values may be separated by carriage return characters. 



Standard l-D-S/li Functions 



Brief descriptions of syntax for APL colls on the I— D— S/II data manipulation 
functions ore listed below. For information on their meaning and use, see the 
I— D-S/II Programmers Reference Manual (CE35) . 

set name 

R*{]DBACCEPT (IFROM] [recordname] CURRENCY) 

areanome 

set name 

R*UDBACCEPT ([FROM] [recordname] REALMHAME) 

dbkey 

If the first parameter is a setname or recordname, this function requires that the 
text of the name be supplied and not the name's Index in UDBNAMES. 
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R*^DDB ACCEPT {I FROM] set name 



NEXT 
PRIOR 
CURRENCY) 
OWNER 



R*-UDBBUFFERS 

R<-UDBCHECK 

Rf-UDBCRPT 



'' nteger 
nteger 
nteger 



R*-UDBCONNECT ( [ recordnameErO] ]setname ) 
R<-nDBDISCONNECT ([ recordname[/'/?OW] ] set name ) 
R*-UDBERASE ([recordname] [ALL][MEMBERS] ) 

dbkey 

R*^CIDBFIND ([recordname]Z)BJr£r[/S] parametername ) 



R*-UDBFIND {ANY recordname ) 

R*-UDBFIND (DUPLICATE recordname ) 

R*-UDBFIND {DUPLICATE[WITHIN]seiname[USING]\iem\ist ) 

[FIRST] 
[NEXT 1 

R*-UDBFIND ( [PRIOR] [ recordname] [IZ/rff/Aflsetnome ) 

[LAST ] realmname 
[count] 

If the first parameter is a keyword, this function requires that the text of the name 
be suppi ied. 



R-^UDBFIND (CURRENT [VITHIN] recordname 



set name 
rea tmname 
keyname 



) 



R^UDBFIND (OWNER [WITHIN] setname) 

R*-UDBFIND {recordname WITHIN aeiname [CURRENT] [USING] itemlist ) 
FIRST 

R^-UDBFIND (NEXT [recordname] USING keyname) 
recordname 

R*-UDBFINISH realmname! ist 

R*-UDBGET recordname 

R*-UDBGET identifier! ist 

[ONLY ALL 1 

R*UDBM0DIFY ( [recordnome] [INCLUDING setname! ist [MEMBERSHIP]]) 



R*UDBM0DIFY ( item! is 



t [ 



[CONNECT 
R*€DBPRIVACY ( SET [DISCONNECT 
[FIND 



ALL ] 
INCLUDING setname! ist [MEMBERSHIP]]) 

privacykey [setname! ist]) 



GET 
MODIFY 
STORE 

R*^QDBPRIYACY (RECORD [FIND 

[ERASE 



CONNECT 
DISCONNECT 
GET ] 



privacykey [recordname! ist]) 
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R*^DDBPRIVACY (ITEM {MODIFY ] privacykey [Itemllst]) 



[UPDATE 1 I SHARE 
R*-DDBREADY ( [realm list] [USAGE MODEl IS ]IRETRIEVAL] ISHAREIN 

[LOAD ] [HOSHARE 
[SHAREAHY 

[REALM 

[record 
r*-udbretain ( [sets 

[setname I i st 

R*-UDBROLL 
R*{]DBRPTSTATS 
R*'UDBSTATSOFF 
R*^QDBSTATSOlf 

R*UDBSTORE ( recordname) 
R*-UDBTRACEOFF option 
R*-UDBTRACEON option 



R*-UDBIF 



( setname 



EMPTY 

MEMBER 

TENANT 



l-D-S/ll Error Reporting and Handling 



The execution of I-D-S/II data manipulation functions always cause a code to be 
returned in the DBSTATUS cell. Values of DBSTATUS greater than zero signify that an 
exception condition has occurred. Successful completion of the data management 
function is indicated by a DBSTATUS of zero. 

Control over exception conditions may be obtained by APL use procedures. 



UDBUSE Function (Use Procedures) 



Syntax: 



code UDBUSE name 
QDBUSE name 



Description: 

The UDBUSE function returns the name of the use procedure associated with the 
specified code. 

APL use procedures are specified and interrogated by the UDBUSE system function. To 
specify a use procedure, the left argument to UDBUSE contains the DBSTATUS value. 
The right argument contains the name of a ni Iodic function or character vector to be 
executed when the DBSTATUS value returned by I-D-S/II is equal to the left argument. 
If an empty vector is supplied for the right argument, the use procedure for the 
DBSTATUS value in the left argument is deleted. More generally, the left argument to 
UDBUSE may be a vector of status codes, in which case, the specified ni Iodic function 
becomes the use procedure for all of the status codes specified. If the right 
argument is empty, use procedures for ail of the specified codes ore removed. 
Finally, the left argument may be a namelist, in which case, there must be exactly as 
many status codes specified as there are names in the use procedure list. 
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Monadically, UDBUSE is used to determine the status codes for which there exists an 
active use procedure or the names of procedures attached to particular status codes. 



ExampI es: 

UDBUSE 10 

This function returns all of the status codes for which there exists a use procedure. 



UDBUSE UDBUSE lO 

This function returns the names of all of the use procedures. 

A status code of zero may be specified for a use procedure in which case that 
procedure will gain control whenever on exception condition occurs for which there 
exists no explicitly named use procedure for that code. The use procedure table is 
of limited size, there will however always be room for 75 use procedures. Whenever 
the current workspace is cleared or a new workspace is loaded, the use procedure 
table is lost and must be set up once again. 
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Section 14 
Packages 



A package is used to hold the definition of one or more functions, or the value of 
one or more variables. A package contains a set of names which ore distinct from 
each other. However, the names within a package need not be distinct from names used 
outside the package or from the name of the package itself. A name must be extracted 
from the package before it con be referenced in the active workspace. Packages can 
be written to or read from files, passed as the argument of a defined function, or 
returned as the result of a defined function. Packages within saved workspaces can 
be copied. 

The package name is displayed by the system command )VARS or as the result of [WZ, . 
The function QNC reports the namecloss of the package as "variable", the function URM 
reports the number of bytes required to store the package and the function QEX may be 
used to expunge a package. The )ERASE command can also be used to expunge a package 
if the package is defined globally. 

The following restrictions apply to the use of packages: 

1. A package is outside the domain of arithmetic, relational, and structural 
f unct i ons. 

2. A package is outside the domain of t, c, and []. 

3. A package cannot be: 

o an item of another array, 
o catenated. 

o inserted into on array via indexed assignment. 

4. The contents of a package cannot be directly displayed. 

The function UPtfAMES can be used to distinguish a variable that is a package from a 
variable that is not a package. For example, the expression [^NAMES X returns a 
matrix when AT is a package and returns an empty vector when X is not a package. 



Package System Functions 

The following system functions are used to create and manipulate packages. When two 
syntax formats are listed for a function, "Monadic Syntax:" refers to the monadic 
function and "Dyadic Syntax:" refers to the dyadic function. 
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UPACK Function (Package Create) 



Syntax: 

R*-UPACK X 
R<-Y UPACK X 



Parameters: 
X \s a name list. 
R is a package. 
Y i s a name list. 



Descr i pt i on : 

Using monadic UPACK, the argument is a namelist which contains the names to be 
included in the resulting pockoge. The result is a package containing each of the 
distinct names included in the argument and the object, if any, to which that name 
refers. If the name in X is the name of a shared variable, the value included in the 
package is the last visible value in the active workspace. (Referring to a shared 
variable with monadic UPACK does not count as a "use" of the shared variable.) 

Dyadically, the UPACK function packages the value X with the name in Y. The right 
argument is any data object (an array or package, but not a function). The left 
argument is a character vector, scalar or 1-row matrix which contains a single name. 
The result is a package which contains the name in the left argument and the data in 
the right argument. 



1. If the same name is included more than once in the right argument X, the extra 
occurrences have no effect. 

2. A misspelled name in the argument does not cause an error message and the 
intended object will be missing from the package. 



Note: 



UPINS Function (Package Insert) 



Syntax: 



R^Y UPIHS X 



Parameters: 



X 



is a package. 



Y 



is a package. 



R 



is a package. 
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Description: 



The UPINS function inserts the package X into the package Y. Both X and Y must be 
packages. The result is a package which contains alt the names along with their 
referents from package X, and, in addition those names that occur in Y but do not 
occur in X, and the objects which are referred to in package Y. 

The resulting package contains all of the names from both of the packages. However, 
when a name in AT is the same as a name in K, it's referent from X is included as the 
referent in the result. 

Note: The names in a package are reported in arbitrary order. The package resulting 
from [^INS need not have names in the identical order as the names which appear in Y. 



UPNAMES Function (Package Names) 



Syntax: 

R't'UPNAMES X 



Parameters: 

X is a package. 

R is a name I ist. 



Descr i pt 1 on : 

The Ji^lifAMES function returns the names in a package X. The argument is any array or 
package. The result is an empty vector whenever the argument is not a package, 
otherwise the result is a character matrix containing the names in the package. The 
matrix has one row for each name, and the longest name determines the number of 
columns. Names are I ef t— j ust i f i ed , with following blanks. 

Note: APL reports the names within a package in arbitrary order. 



UPNC Function (Package Name Correspondence) 



Syntax: 



UPtfC X 



R^Y UPNC X 



Parameters : 



is 0 package. 



Y 



specifies on optional argument which is a name I ist. 



R 



is a simple integer vector. 
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Descript ion: 

Monadically, UPNC returns the nameclass of each of the names in the package. 
Dyadically. QPHC returns the nameclass of each of the specified names in a package. 

The right argument is a package. The left argument is an optional nomelist. It is 
not necessary that a name included in the left argument also be present in the 
package, or that the names ore well formed. The result is an integer vector which 
indicates the nameclass of package X names. Whenever UPNC is used with a left 
argument, the result contains one item corresponding to each name in the left 
argument . 

Monadically, the result of the UPNC function contains one item for each name included 
within the package X in the same order as the names reported by UPNAHES X, leading to 
the following identity: 

UPNC X (UPNAHES X) UPNC X 

The class of object to which the name refers is indicated by an item of the result. 
The following table shows the relationship: 



CODE 


NAME 




-1 


No referent 




e 


Not present 


in the package 


2 


Refers to a 


variable 


3 


Refers to a 


function 


4 


Is not wel 1- 


-formed 



The code used in the result of OA^C determines the code in the result of DPA^C. The 
value 1 cannot appear in the result of UPNC because a package cannot contain a label. 
The value —1 does not occur in the result of UNC. 



UPVAL Function (Package Value) 



Syntax: 

R*-Y UPVAL X 



Parameters: 

X is a package. 

r is a namelist containing one name. 
R is an APL value. 



Description: 

The UPVAL function returns the value of the variable named in Y from the package X. 
The left argument is a character vector, scalar, or matrix. The referent in X must 
be a variable and the left argument must contain one name. APL reports a DOMAIN ERR 
message when Y does not meet those requirements. The result is the value of the 
variable which is named in Y. 
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UPDEF Function (Package Definition) 



Syntax: 

UPDEF X 
Y UPDEF X 

Parameters: 

X is a package. 

Y is a name I ist. 

Description: 

Monadically, UPDEF defines all of the names in the package right argument. 
Oyodicalty, UPDEF defines those names in the package right argument that appear in 
the left argument. 

Each name in the left argument must: 

o Be we 1 1 formed. 

o Be contained in package X. 

o Not have an active function which is a visible referent in the workspace. (Its 
referent may not appear on the state indicator.) 

Monadically. the UPDEF function defines every name in package X in the active 
workspace with the referent from the package. Dyadicalty, the UPDEF function defines 
each name in the namelist Y in the active workspace with the referent from the 
package X. A name existing in the package without a referent is expunged when [^DEF 
is used to bring the name into the workspace. 

Possible Errors: 

A DOHAIH ERR is reported if: 

o any of the names in Y do not meet requirements stated in description. 

UPPDEF Function (Protected Package Definition) 

Syntax: 

UPPDEF X 
R^Y UPPDEF X 
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Parameters: 



X 



is a package. 



Y 



is a name I ist. 



R 



i s a name list. 



Descript ton: 

Monodically, UPPDEF defines all of the names in the package right argument that 
currently have no value. Dyadically, UPPDEF defines those names that appear in the 
package right argument, are named in the left argument, and do not currently have a 
value. The explicit result for both cases is a namelist containing names of objects 
not defined because they had values. 

UPPDEP assigns a new meaning to a name with no current use and never expunges or 
changes an existing name's referent. (It can be compared to the system command 
)PCOPY , except that )PCOPY refers to the global and not to the visible meaning of 
each name.) 

When UPPDEF is used dyadically. the left argument Y is a namelist that specifies the 
names which are to be defined. Each name in Y must be included as a name in package 



When ^PDEF is used with two arguments, each name In Y (or when UPPDEF is used with 
one argument, each name in X) which has no visible referent in the workspace, is 
given the value which it has in the package. 

The result is a namelist containing the names in the package which were not defined 
because they already exist in the active workspace. 



UPSEL Function (Package Select) 



Syntax: 

R^Y UPSEL X 



Parameters: 
X is a package. 
Y ISO name list. 
R is a package. 



Description: 

The UPSEL function returns a package containing those names from the package right 
orgument that appear in the namelist left argument. Each name specified in the 
namelist must be contained within the package. 
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UP EX Function (Package Expunge) 



Syntax: 

R^Y UPEX X 

Parameters: 
X is a package. 
Y is a name I ist. 

R is a package. 

Descrlpt ion: 

The UPEX function returns a copy of the package right argument excluding the names 
specified in the name! ist left argument. 



UPLOCK Function (Package Lock) 



Syntax : 

Rf-Y UPLOCK X 
UPLOCK X 



Parameters: 

X is a package. 

Y is an optional name I ist. 

R is a package. 



Descr ipt ion: 

Monodlcaliy. UPLOCK returns a package identical to the right argument except that all 
of the defined functions are locked. Dyadicoliy. UPLOCK returns a package identical 
to the right argument except that all of the defined functions named in the left 
argument ore locked. 

Each of the names must be well formed and must be a name which is present in package 
X and is used there as the name of a function. The function in X need not be 
previously unlocked. 

The result is a pockage which contains the same names with the same referents as 
package X. The exceptions are as follows: 

o When [^LOCK has two arguments, the functions which are unlocked in X and named in 
r are locked in the resulting package. 

o When [^LOCK is used with one argument, all functions are locked in the resulting 
package. 
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Section 15 

CP-6 APL Graphics 



CP-6 APL provides four system functions which produce device independent graphics 
output. Additional system functions and variables are also provided which may be 
used to control the graphics device or the appearance of the graphics output. The 
CP-6 DIGS Reference Manual (CE72) provides a more detailed definition of the general 
capabilities and functionality available. This section contains a simple overview of 
the graphics capability available within APL. 

The APL graphics capabilities are sub-divided into the five areas: 

o Output Functions 
o Segment Primitives 
o Attribute Variable 
o Viewing Variables 
o Control Primitives 

The graphics output primitives include the ability to draw lines, draw and optionally 
fill polygons, draw markers and generate text. Graphics output is subject to the 
controls provided by the other graphics capabilities and the device on which it is 
displayed. 

All graphics output appears in either a temporary or a retained segment. CP-6 APL 
provides the ability to create segments, delete segments, rename segments, select 
segments, and to inquire about the attributes of segments. A retained segment 
defines an image which is a part of the whole picture displayed on a view surface. 
Attributes of a retained segment may be dynamically modified, thereby changing the 
image on the view surface. 

The capabilities provided by the graphics attribute variables allow control over the 
appearance of graphics output primitives. The appearance includes such items as the 
color, intensity, line widths, marker symbols, and the text font. The graphics 
viewing variables control the location, size and rotation of graphics output. The 
viewing variables include such items as the graphics window, the viewport, and the 
image transformation variables. 

The graphics control primitives provide the capabilities required to initiate an APL 
graphics session, select a graphics device, determine the device capabilities, and 
define the mappings between certain attribute settings and the corresponding device 
color or intensity. 

The following APL program demonstrates the use of APL graphics. It does all that is 
necessary within APL to produce graphics output on a graphics terminal. 



15] 0 CREATE OUTLINE OF HOUSE 

[6] HOUSE'*-! 2p 1659969111169 6-^10 

[7] USRLINE HOUSE 

[8] a DRAW DOOR 

[9] DOOR^k 2p 7 1 7 3 8 3 8 1^-10 

[10] [y^RLINE DOOR 

[11] A DRAW SHALL WINDOW 

[12] WIlfDOWlt-5 2p 222332322 2^10 

[13] USRLINE WINDOWl 

Ilk] a DRAW LARGE WINDOW 

[15] WIND0W2^5 2p 424464624 2^10 

[16] WRLINE WIND0W2 



[1] 
[2] 
[3] 
[4] 



V HOUSE_EXAHPLE 
\JGRINIT 

UGRINITSURF 1 
DGRSURFACE 1 
QGRTSEGO 



a PREPARE TERMINAL FOR GRAPHICS 
fi SELECT TERMINAL FOR GRAPHICS 
a OUTPUT INTO TEMPORARY SEGMENT 



a INITIALIZE GRAPHICS 



V 
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Figure 15-1. Graphics Output Example 



This example demonstrates the necessary preparations before graphics output may be 
created. The QGRIHIT, UGRINITSURF and [y^RSURFACE functions must all be executed 
before any graphics output is created. The use of these functions is described under 
the topic Graphics Control Functions and Variables. 

The function UG-RTSEGO is used to indicate that the following output is temporary (not 
to be retained across screen clears for example). This function is described under 
the topic Graphics Segment Functions. A graphics segment (temporary or retained) 
must also be in use before graphics output moy commence. 

The function QGRLIHE is one of the five graphics output functions available in CP-6 
APL. This function connects each of the points specified with a line. The type of 
line drawn may be controlled by variables that are described under the topic Graphics 
Attribute Variables. 



Graphics Output Functions 



Five system functions in CP-6 APL are used to produce graphics output. Each of the 
functions supply a different type of graphics output from a similar graphics 
argument. The data to be displayed graphically is provided as either an N— by-2 or 
N-by-3 array. The columns are treated as X, Y, and optional Z components of a 
graphical position. If the data to be displayed is not a matrix, a RANK ERR is 
reported. If the data to be displayed is not an N-by-2 or N-by-3 array, a LENGTH ERR 
is reported. If the data to be displayed is not a simple numeric array, a DOMAIN ERR 
is reported. 

If an APL graphics session has not been initiated by executing the UGRINIT system 
function, or if a device has not been initialized and selected, or there is not a 
currently open segment, a DOMAIN ERR is reported. (Entering a ')?' command indicates 
which error has occurred). 
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UGRLINE Function (Draw Line) 



Syntax: 

DdRLINE DATA 



Parameters: 

DATA is a simple array of shape N-by-2 or N-by-3 containing only scalar numbers. 



Description: 

The Uf^RLIHE function defines the simplest form of graphical output. A line is drown 
connecting each of the positions in the data array provided. 



Example: 

H0USE^7 2p.6 .1 .9 .5 .6 .9 .1 .9 .1 .1 .6 .1 .6 .9 
DtiRLIHE HOUSE 

This example creates a simple stick house on the currently selected view surface. 



Possible Errors: 



A RANK ERR is reported if: 

o the right argument is not a matrix 

A LENGTH ERR is reported If: 

0 the right argument is not on N-by— 2 or N-by— 3 matrix 
A DOMAIN ERR is reported if: 



o the right argument is not simple or all numeric 

o APL graphics is not initialized 

o there is not an open segment 

o the current value of QGRLl is not supported 

0 the current value of UORLS is not supported 

o the current value of UGRLW is not supported 

o the current value of UQRPEN is not supported 



UGRMARK Function (Draw Marker Symbols) 



Syntax: 

DGRHARK DATA 
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Parameters: 

dkTk is a simple array of shape N-by-2 or N-by-3 containing only scalar numbers. 

Descript ion: 

The ^BMhM. function produces a marker symbol (as selected by the \}fiRHkRKER system 
variable), at each of the positions indicated by the data array. 

Example: 

CURVE^l 2p0 0 .2 .1 .3 .4 .5 .5 .7 .ij .8 .1 .9 
DCiRMARK CURVE 

Possible Errors: 

A RANK ERR is reported if: 

o the right argument is not a matrix 

A LENGTH ERR is reported if: 

o the right argument is not an N-by— 2 or N-by-3 matrix 
A DOMAIN ERR is reported if: 

o the right argument is not simple or not all numeric 

o APL graphics is not initialized 

o there is not an open segment 

o the current value of QC/ZL/ is not supported 

o the current value of [YiRMARKER is not supported. 

o the current value of UHiRPEN is not supported 

UGRPOLYGON Function (Draw Polygon) 

Syntax: 

UGRPOLYGON DATA 

Parameters: 

DATA is a simple array of shape N-by-2 or N-by-3 containing only scalar numbers. 

Descr i pt ion: 

The UGRPOLYGON function produces a polygon whose vertices ore the positions provided 
in the data array. The appearance of the polygon can be controlled through 
assignment to the attribute variables. 

Examp I e : 

PARALLELS^k Zp.2 .3 A .7 .8 .7 .6 .3 
UGRPOLYGON PARALLELS 
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Possible Errors: 



A RANK ERR is reported if: 

o the right argument is not a matrix 

A LEHGTH ERR is reported if: 

o the right argument is not an N-by-2 or N-by-3 matrix 
A DOHAIK ERR is reported if: 

o the right argument is not simple or not all numeric 

o APL graphics is not initialized 

o there is not on open segment 

o the current value of UGRPEN is not supported 

o the vertices ore not coplanor 

o the current value of DGRFILL is not supported 

o the current value of OQRYERTEX is not supported 

o the length of [yiRVERTEX is not equal to the first dimension of the right argument 
o the current value of QC^L/ is not supported 



UGRDRAW Function (Draw Picture) 



Syntax: 

/ DiRDRAV DATA 



Parameters: 

7 is the integer scalar value 0. 1. or 2. 

DATA is a simple numeric array of shape N-by-3 or N— by-4. The first column contains 
the values 0 or 1 only. The last 2 or 3 columns the X, Y or X. Y. and Z world 
coordinates. 



Descr i pt i on : 

The ^RDRAV function provides a mechanism to define a sequence of strokes or 
polygons. A new stroke begins when a row of the data in the right argument contains 
the value 1 in the first column. A stroke ends when all positions in the remaining 
rows have been connected or before the next row which contains a 1 in the first 
CO I umn . 

If / is 0» each stroke is joined by a line. If / is 1, each point is marked. If / 
is 2, each stroke is treated as a polygon. 



In the fol lowing example, the picture of the house created in the example at the 
beginning of this section is produced by a single use of the \yiRDRAW function rather 
than executing the function QCRLIHE four separate times. 



Example: 



[11 
[21 



V DRAW_EKAHPLE 

(?♦ 1 ) ,HOUSE) , [ 1 1 ( 1 ) ,DOOR), [ 1 J (5» I) .VINLOUZ 



0 QGRDRAW U 



7 
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Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a matrix, 
o the left argument Is not a scalar. 

A LENGTH ERR is reported if: 

o the right argument is not on N-by-3 or N-by-4 matrix, 
o the left argument is not a single value. 

A DOMAIN ERR is reported if: 

o the right argument is not simple or all numeric, 

o the left argument is not simple or not numeric, 

o APL graphics is not initialized 

o there is not an open segment 

o the current value of UGRLl is not supported 

o the current value of UORPEN is not supported 

o the current value of UGRLS is not supported 

o the current value of [XiRLV Is not supported, 

o the current value of UGRMARKER is not supported 

o the current value of UCRFILL is not supported, 

o the current value of USRVERTEX is not supported. 

o the length of UORVERTEX is not equal to the number of points in the stroke, 

o the vertices ore not coplonor. 



UGRTEXT Function (Draw Text) 



Syntax: 

POSITION DGRTEXT STRING 



Parameters: 

POSITION is a simple numeric vector of 2 or 3 items which indicate a graphical 
posi t ion. 

STRING Is a simple character vector containing the characters to be displayed on 
the graphics device. 



Descr i pt ion: 

The UGRTEXT function causes the character vector to appear on the graphics device 
starting at the position indicated. The appearance of the text depends on the 
current definition of the text graphics attribute variables. 



Examp I e : 

.125 .25 UGRTEXT 'HERMOSA' 

This example displays the text *HERHOSA* at the world coordinate position 
(0.125,9.25). 
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Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a vector 

o the right argument is not a vector or scalar 

A LENGTH ERR is reported if: 

o the left argument does not contain 2 items 

A DOMAIN ERR is reported if: 

o the right argument is not simple and all character scalars 

o the left argument is not simple and all numeric 

o APL graphics is not initialized 

0 there is not an open segment 

o the current value of UPRPEN is not supported 

o the current value of DRRTEXT is not supported 

o the current value of DGRFONT is not supported 

o the string contains illegal characters 

o the vectors established by DQRCHPLANE and \y}RCHUP are parallel 

o the string contains more than 256 characters 

o DSRCHPLANE and DURCHUP matrix cannot be inverted 



UGRWORLDC Function (Map to World Coordinates) 



Syntax: 

DATA0*-D(iRVORLDC DATAl 



Parameters: 

DATAO is a simple array of shape N-by-2 or N-by-3 containing only scolar numbers. 
DATAl is a simple array of shape N-by-2 or N-by-3 containing only scalar numbers. 



Description: 

The [^RWORLDC function returns the world coordinates associated with the normalized 
device coordinates supplied as the right argument. 



Examp I e : 

DCRWORLDC 4 2p.2 .3 .4 .7 .8 .7 .6 .3 
0.2 0.3 
OA 0.7 
0.8 0.7 
0.6 0.3 

Since the default image transformation is an identity matrix, the positions supplied 
to this function ore mapped to themselves. 
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Possible Errors: 

A RAHK ERR is reported if: 

o the right argument is not o matrix 

A LENGTH ERR is reported if: 

o the right argument is not an N-by-2 or N-by-3 matrix 
A DOMAIlf ERR is reported if: 

o a specified NDC position is outside the current viewport 
o the world coordinote transformation is not invertible 
o the view plane normal and view up direction ore parallel 
0 APL graphics is not initialized 

0 the projection and view parameters are inconsistent 
o the clipping planes are inconsistent 



UGRMDC Function (Map to NDC) 



Syntax: 

datao*q;rndc datai 



Parameters: 

DATAO is a simple array of shape N-by-2 or N— by-3 containing only scalar numbers. 

DATAI is a simple array of shape N— by— 2 or N-by— 3 containing only scalar numbers. 



Descript ion: 

The UGRtfDC function returns the normalized device coordinates associated with the 
world coordinates supplied as the right argument. 



Example: 

DSRNDC * 2p.2 .3 .4 .7 .8 .7 .6 .3 
0.2 0.3 
0.4 0.7 
0.8 0.7 
0.6 0.3 



Possible Errors: 

A RAHK ERR is reported if: 

o the right argument is not o matrix 

A LENGTH ERR is reported if: 

o the right argument is not an N-by-2 or N-by-3 matrix 
A DOMAIN ERR is reported if: 

o a specified world position is outside the current window 

and clipping is enabled 
o the view plane normal and view up direction are parallel 
o APL graphics is not initialized 

o the projection and view parameters are inconsistent 
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DGRNDC Function (Map to NDC) 



CE38-e4 



UORTEXTX Function (Inquire Text Extent) 



Syntax: 

POSO^POSl UGRTEXTX STRIHG 



Parameters: 

POSO is a simple numeric vector of 2 or 3 items which indicate a graphical 
position in world coordinates. 

POSl is a simple numeric vector of 2 or 3 items indicating o graphical position 
in world coordinates. 

STRING is a simple character vector containing the characters to be displayed on 
the graphics device. 



Description: 

The ^RTEXTX function is used to return the extent of the specified character string 
on the specified view surface, if the character string is drawn, unjustified, 
beginning at the position .indicated by the left argument. 



Example: 

.125 .25 DGRTEXT 'HERMOSA BEACH' 

0.13 0 



Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a vector 

o the right argument is not a vector or scalar 

A LENGTH ERR is reported if: 

o the left argument does not contain 2 items 
A DOMAIN ERR is reported if: 

o the right argument is not simple and oil character scalers 
o the left argument is not simple and all numeric 
o APL graphics is not initialized 
o there is not an open segment 

o the current volue of UGRFONT is not supported 
o the string contains illegal characters 

o the vectors established by \y}RCHPLANE and UGRCHUP ore parallel 

o the string contains more than 256 characters 

o the QGRCHPLANE and DGRCHUP matrix cannot be inverted 
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DGRTEXTX 
Function (Inquire Text Extent) 
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UGRCP Function (Current Position) 



Syntax: 



Parameters: 

POS is a simple numeric vector of 2 or 3 items which indicate a graphical 
position in world coordinates. 



Descri pt ion: 

The UGRCP ni Iodic function is used to return the current drawing position in world 
coordinates. 



Example: 

UCRCP 
0.125 0.25 



Possible Errors: 

A DOMAIN ERR is reported if: 

o APL graphics is not initialized 



Graphics Segment Functions 

All graphics output occurs in graphical segments. The segments partition the output 
primitives such that the output of each primitive occurs in one and only one segment 
and each segment contains only graphic primitive output. Two types of segments may 
be used: retained segments and temporary segments. 

Graphic output directed to a temporary segment exists for the life of the current 
frame. Output directed to a retained segment may appear in multiple frames depending 
on its visibility attribute. Many retained segments may be used to represent the 
image on the view surface. Retained segments are identified by their names which 
must be on integer number in the range 1 to 65535. 



UGRSEGOPEN Function (Create a Retained Segment) 



Syntax: 

UHRSEGOPEH SEG 
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DdRSEGOPEN 
Function (Create a Retained Segment) 
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Parameters: 

SEG is a simple numeric scalar containing the number of the segment to be 
created. 



Descript ion: 

The UCRSEGOPEH function creates a new empty retained segment. The dynamic attributes 
for the new segment are determined by the current attribute values for the retained 
segment dynamic attributes. The set of currently selected view surfaces is recorded 
with the newly created retained segment. Throughout the life of the retained 
segment, the image it defines appears on each view surface in this list. 

The newly created segment becomes the currently open segment. Subsequent execution 
of graphics output functions are recorded in this retained segment. If the retained 
segments visibility attribute is visible, the execution of graphics output functions 
also results in new information appearing on the view surfaces selected by the 
segment. While a segment is open, the viewing parameters may not be altered and view 
surfaces may not be selected or deselected. 



Example: 

DGRSEGOPEH 314 



Possible Errors: 

A LEHGTH ERR is reported if: 

o the right argument does not contain exactly one item 
A DOMAIN ERR is reported if: 

o the right argument is not simple or numeric 

o there is no currently selected view surface 

o on open segment already exists 

o the specified retained segment already exists 

o there is on illegal image transformation 

o the view plane normal and view up direction are parallel 

o the viewing parameters ore inconsistent 

o the clipping parameters are inconsistent 

o APL graphics is not initialized 



UGRSEGCLOSE Function (Close Retained Segment) 



Syntax: 

UGRSEGCLOSE 



Description: 

The UGRSEGCLOSE function closes currently open retained segments. Output primitives 
can no longer be executed. Closing a retained segment has no effect on its 
visibility or other segment attributes. 
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UGRSEGCLOSE 
Function (Close Retained Segment) 
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Example: 

DliRSEGCLOSE 



Possible Errors: 

A DOMAIN ERR is reported if: 

o no open retained segment exists 
o APL graphics is not initialized 

UGRSEGDEL Function (Delete Retained Segment) 

Syntax : 

UGRSEGDEL SEGS 

Parameters: 

SEGS is a simple integer vector contoining the numbers of the segments to be 
deleted. 

Descr i pt i on: 

The UGRSEGDEL function deletes the specified retained segment. If the retained 
segment's visibility attribute is visible, its image is removed from each view 
surface on which it appears. After a retained segment is deleted, it is as if the 
segment hod never existed. 

Example: 

UGRSEGDEL 31* 1 
This example causes segments 314 and 1 to be deleted. 

Possible Errors: 

A RAHK ERR is reported if: 

o the right argument is not a scalar or vector 
A DOHAIH ERR is reported if: 

o the right argument is not simple or does not have integer values 

o APL graphics is not initialized 

o the specified retained segment does not exist 
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UGRSEGDEL 
Function (Delete Retained Segment) 
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UGRSEGRElf Function (Rename Retained Segment) 



Syntax: 

DSRSEGREN SEGZ 

Parameters: 

SEGZ is a simple integer vector containing 2 items which are the current segment 
number and the new number by which that segment is to be Icnown. 

Description: 

The UGRSEGRElf function renames the specified segment. The original retained segment 
name can no longer be referenced. This function has no visible effect. 

Example: 

DGRSEGREN 2 3U 

This example changes the name (segment number) of segment 2 to number 314. 

Possible Errors: 

A RANK ERR is reported if: 

o the right argument is not a scalar or vector 

A LENGTH ERR is reported if: 

o the right argument is not of length 2 

A DOMAIN ERR Is reported If: 

o the right argument is not simple or not near integer 

o the first item of the right argument is not a retained segment number 

o the second item of the right argument is a currently existing segment number 

o APL graphics is not initialized 



UGRSEGSURFS Function (Inquire Segment Surfaces) 



Syntax: 

SURFS*{}GRSEGSURFS SEG 

Parameters: 

SEG is a simple numeric scalar containing the number of an existing segment. 
SURFS is a simple integer vector of view surface numbers. 
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DGRSEGSURFS 
Function (Inquire Segment Surfaces) 
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Descr ipt ion: 

The UGRSEGSURFS function returns the number of the view surfaces which were selected 
when the retained segment was created. 

Example: 

DSRSEGSURFS 314 

1 

This example demonstrotes that graphics output to segment 314 appears on view surface 
1 . 

Possible Errors: 

A LENGTH ERR is reported if: 

o the right argument does not contain exactly one item 
A DOMAIN ERR is reported if: 

o the right argument is not simple or near integer 
o the specified segment does not exist 
0 APL graphics is not initialized 

UGRSEGS Function (Inquire Retained Segment Names) 

Syntax: 

SEGS*^RSEGS 

Parameters : 

SEGS is a simple integer vector result. 

Descr ipt ion: 

The UGRSEGS function returns the numbers of all of the current retained segments. 

Example: 

UGRSEGS 

3 314 

This example displays the number of current retained segments, in this case there are 
currently two retained segments numbered 3 and 314. 

Possible Errors: 

A DOMAIN ERR is reported if: 

o APL graphics is not initialized 
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UGRSEGS 

Function (Inquire Retained Segment Names) 
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UGRSEGCURR Function (Inquire Open Segment) 



Syntax: 

SEQ*{y;RSEGCURR 

Parameters: 

SEG a simple integer scalar result. 
Descript ion: 

The result of the UGRSEGCURR function is 0 if there is not a currently open retained 
segment, or it is the number of the currently open retained segment. 

UGRTSEGO Function (Create Temporary Segment) 

Syntax : 
UGRTSEGO 

Descript ion: 

The ^RTSEGO creates an open temporary segment. Subsequent execution of output 
primitives result in information appearing on the currently selected view surfaces. 
While a temporary segment is open, the viewing parameters may not be altered and view 
surfaces may not be selected or deselected. 

Example: 

DGRTSEGCO 

Possible Errors: 

A DOMAIN ERR is reported if: 

o APL graphics is not initialized 

o the set of selected view surfaces is empty 

o an open segment already exists 

o the viewing parameters are inconsistent 

o the clipping parameters are inconsistent 
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UGRTSEGO 

Function (Create Temporary Segment) 
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UGRTSEGC Function (Close Temporary Segment) 



Syntax: 

DdRTSEGC 

Descript ion: 

The UGRTSEGC function closes the currently open temporary segment. Output primitives 
may no longer be executed. 

Example: 

DGRTSEGC 

Possible Errors: 

A DOMAIN ERR is reported if: 

o APL graphics is not initialized 
o there is no open temporary segment 

UGRTSEG Function (Inquire Open Temporary Segment) 

Syntax: 

LOGL*-DGRTSEG 

Parameters : 

LOGL is a scalar logical value 0 or 1 . 
Descr i pt i on : 

The result of executing the UGRTSEG function is the value 1 if there is a temporary 
segment currently open, otherwise the result is 0. 

Examp I e : 

UGRTSEG 

0 

Possible Errors: 

A DOHAIH ERR is reported if: 

o APL graphics is not initialized 
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BiRTSEG 

Function (Inquire Open Temporary Segment) 
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UGRSEGVrSIBILITY Function (Segment Visibility) 



Syntax: 

LOGL0'*-LOGLl UGRSEGVISIBILITY SEGS 
LOGL0<- UGRSEGVISIBILITY SEGS 



Parameters: 

LOGLO is a simple logical vector. 

SEGS is a simple integer vector containing the numbers of retained segments. 

LOGLl is a simple logical vector of the some length as SEGS. Or. it is a single 

logical value to be used for each item in SEGS. 



Description: 

The UGRSEGVISIBILITY function is used to modify or inquire about the current value of 
the segment visibility attribute for each segment number in the right argument. If 
the left argument Is not provided, the result has the same length as the right 
argument. In this cose, each result value is 1 if the segment visibility attribute 
is ^VISIBLE' or 0 if the segment visibility attribute is 'INVISIBLE'. 

If the left argument is provided, the values specified by the left argument are used 
OS the new segment visibility dynamic attribute for each of the segments specified in 
the right argument; the result is an empty vector. The value 1 is used to set the 
segment visibility to 'VISIBLE' and the value 0 is used to set the segment visibility 
to 'INVISIBLE'. 



Exomp I e : 

1 UGRSEGVISIBILITY 3 3U 
UGRSEGVISIBILITY 3 3lk 

1 1 



Possible Errors: 

A RANK ERR is reported if: 

o the left or right arguments are not vectors or scalars 
A LENGTH ERR is reported if: 

o the left argument is not the same length as the right argument and the left 
argument is not a single item. 

A DOMAIN ERR is reported if: 

o the right argument contains an item that is not a simple integer value 
o the left argument contains an invalid value 

o the right argument contains a number which is not the number of a retained 
segment 

o APL graphics is not initialized 
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UGRSEGVISIBILITY 
Function (Segment Visibility) 
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UGRSEGHIGHLIGHT Function (Segment Highlight) 



Syntax: 

LOGL0*-LOGLl UGRSEGHIGHLIGHT SEGS 
LOGLO^ UGRSEGHIGHLIGHT SEGS 



Parameters: 

LOGLO is a simple logical vector. 

SEGS is a simple integer vector containing the numbers of retained segments. 

LOGLl is a simple logical vector of the same length as SEGS. Or. it is a single 

logical value to be used for each item in SEGS. 



Descr ipt ion: 

The UGRSEGHIGHLIGHT function is used to modify or inquire on the current value of the 
segment highlighting attribute for each segment number in the right argument. If the 
left argument is not provided, the result has the same length as the right argument. 
In this cose, each result value is 1 if the segment highlighting attribute is 
^HIGHLIGHTED*, or 0 if the segment highlighting attribute is ' HOH-HIGHLIGHTED* . 

If the left argument is provided, the values specified by the left argument are used 
as the new segment highlighting dynamic attribute for each of the segments specified 
in the right argument; the result is on empty vector. The value 1 is used to set the 
segment highlighting to 'HIGHLIGHTED* , and the value 0 is used to set the segment 
highlighting to 'NON-HIGHLIGHTED* . 



Example: 

I UGRSEGHIGHLIGHT 3 3U 
UGRSEGHIGHLIGHT 3 3H 

1 1 



Possible Errors: 

A RANK ERR is reported if: 

o the left or right arguments ore not vectors or scalers 
A LENGTH ERR is reported if: 

o the left argument is not the same length as the right argument and the left 
argument is not a single item 

A DOMAIN ERR is reported if: 

o the right argument contains an item that is not a simple integer value 
o the left argument contains an invalid value 

o the right argument contains a number which is not the number of a retained 
segment 
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UGRSEGHIGHLIGHT 
Function (Segment Highlight) 



CE38-04 



DGRVISIBILITY Variable (Set/Inquire VisibUity) 



Syntax: 

DSRVISIBILITY<-LOGL 

Parameters: 

LOGL is either a scalar numeric value 0 or 1 . Or. it is a simple vector 
containing the characters 'VISIBLE' or 'INVISIBLE*. 

Description: 

The UGRVISIBILITY system variable is used to define the default segment visibility 
attribute. This value is used when a new segment is created by the QGRTSEGO or 
DGRSEGOPEtf system functions. 

Example: 

QGRVISIBILITY^l 
UGRVISIBILITY 

1 

Possible Errors: 

A RANK ERR is reported if: 

o a character value assigned is not a scalar or vector 
A LENGTH ERR is reported if: 

o a numeric value assigned contains more than one item 

A DOMAIN ERR is reported if: 

o the value assigned is not simple. 

o a numeric value assigned is not 0 or 1 

o a character value assigned is not a legal keyword 

UGRHIGHLIGHT Variable (Set/Inquire Highlighting) 

Syntax : 

DGRHIGHLIGHT^LOGL 

Parameters: 

LOGL is either a scalar numeric value 0 or 1 . Or, it is a simple vector 
containing the characters 'HIGHLIGHTED' or 'NON-HIGHLIGHTED' . 
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DGRHIGHLIGHT 
Variable (Set/Inquire Highlighting) 
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Descript ion: 

The USRHIGHLIGHT system variable is used to define the default segment highlighting 
attribute. This value is used when a new segment is created by the USRTSEGO or 
DGRSEGOPEN system functions. 



Example: 

UGRHIGHLIGHT<-1 
DGRHIGHLIGHT 

1 



Possible Errors: 

A RAlfK ERR is reported if: 

o a character value assigned is not a scalar or vector 
A LEttGTH ERR is reported if: 

o a numeric value assigned contains more than one item 

A DOMAIN ERR is reported if: 

o the value assigned is not simple. 

o a numeric value assigned is not 0 or 1 

o 0 character value assigned is not a legal keyword 



Graphics Attribute Variables 



The graphics output functions use the current values of the graphics attribute system 
variables to determine the actual appearance of the graphics output. These system 
variables may be referenced to obtain their current value, assigned new values, or 
localized within functions. When localized, these system variables maintain their 
previous value unless reassigned. 

Values assigned to these attributes affect future use of their associated graphics 
output functions. 

The assignment of these attribute variables can result in a DOMAIN ERR report from 
APL for the following reasons: 

o the attribute value is invalid 
o APL graphics is not initialized 

Other errors can include RANK ERR, LENGTH ERR, and DOMAIN ERR when requirements set 
out by the parameter definition for the variable are not met. 
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Graphics Attribute Variables 
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UGRMARKER Variable (Marker Symbol) 



Syntax: 

{y^RMARKER^-KEYWORD 



Parameters: 

KEYWORD is a scalar integer value which indicates the number of the desired 
marker symbol . 



Description: 

The UGRMARKER vorioble is used by the UGRMARK system function to specify a marker 
symbol. The valid volues are integers in the range 1 through the device driver 
defined maximum. The values 1 through 5 always produce the symbols: dot, star, 
capital letter 0 and capital letter X. Legal values greater than 5 produce symbols 
determined by the device. The default value is 1. 



Examp I e : 

[}GRHARKER^2 
DSRHARKER 

3 



UGRPINS Variable (Polygon Interior Style) 



Syntax: 

DGRPINS't-KEYUORD 



Parameters: 

KEYWORD is a simple character vector containing one of the keyword values: 
*PLAIH', *SHADED', or 'PATTERNED'. 



Description: 

The OGRPINS variable is used by the UQRPOLYGOlf system function to determine the 
method for filling the image of the interior of a visible polygon. The default value 
is 'PLAIN*. 



Examp I e : 

DGRP I NS^* SHADED* 
WRPINS 

SHADED 
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UGRPINS 

Variable (Polygon Interior Style) 
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UGRPES Variable (Polygon Edge Style) 



Syntax: 

DSRPESt-KEYVORD 



Parameters: 

KEYWORD is a simple character vector containing one of the keyword values: 
'SOLID* or 'INTERIOR'. 



Descript ion: 

The UORPES voriable is used by the OGRPOLYGOl/ system function to determine the method 
for forming the image of the border (edges) of a visible polygon. The default value 
is 'SOLID'. 



Example: 

UGRPES*-' SOLID' 
DGRPES 

SOLID 



UGRLW Variable (Line Width) 



Syntax: 

QGRLU^N 



Parameters: 

N specifies the relative width of the imoge of a visible line. 



Descript ion: 

The UGRLW variable specifies the relative width of the image of a visible line 
generated by the UGRLIHE system function. The specified value must be in the range 
from 0 to 1 inclusive. The default value is 0. 



Example: 

UGRLW<-. 0625 
UGRLW 

0.0625 
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UGRLW Variable 



(Line Width) 
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UGRLI Variable (Line Index) 



Syntax: 



Parameters: 

/ is a simple integer scalar value. 



Description: 

The DGRLI variable specifies the index used to select the color or intensity of the 
image of a visible line, murker, or polygon edge (whose UGRPES is 'SOLID'). This 
value only applies to the system functions {^iRLItfE, ^(iRMARKER, and UQRPOLYGOlf. The 
default value is 1. 



Example: 

C3C/?L/<-2 
USRLI 

2 



UGRLS Variable (Line Style) 



Syntax: 

DGRLSf-I 



Parameters : 

/ is a scalar integer value. 



Description: 

The UORLS variable is used by the UGRLIt/E function to determine the style of the 
image of a visible line (e.g., solid, dashed). The default value is 1 which 
corresponds to a solid line. 



ExampI e: 

DSRLS^k 
DSRLS 
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UGRPEM Variable (Pen) 



Syntax: 



Parameters: 



is a scalar integer value. 



Description: 

The UGRPEH variable may be used by all output primitives to distinguish the image of 
their output. The particular values of QQRLI, UliRLS , UGRLV, and UGRTEXTI which 
correspond to a particular pen value ore implementation and device dependent. The 
default value of 0 corresponds to the current settings or USRLI , QCRLS , DGRLW , and 
UdRTEXTl. All other UGRPEN values override these values. 



Example: 

UGRPENf-Z 
DGRPEN 

2 



UQRFONT Variable (Font) 



Syntax: 

QGRFONTtrl 



Parameters: 

/ is a scalar integer value. 



Descr i pt ion: 

The [y^RFONT variable Is used by the ly^RTEXT function to specify the style of a 
visible character. Values range from 1 to a device dependent maximum. The default 
value of 1 corresponds to ASCII. 



Example: 



n(^RF0NT^-29 
UliRFOMT 



fl SELECT APL FONT 



29 
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DGRFOHT Variable (Font) 
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UGRTEXTI Variable (Text Index) 



Syntax: 
Parameters : 

/ is a scalar integer value. 
Description: 

The UGRTEXTI variable is used by the UGRTEXT function to select the color or 
intensity of the images of a visible character. The default value is 1. 

Example: 

DSRTEXTI*-3 
QSRTEXTI 

3 

UGRCHSIZE Variable (Character Size) 

Syntax: 

OSRCHSIZE'-NN 

Parameters: 

NH is a simple two item numeric vector. 
Oescr i pt ion: 

The ly^RCHSIZE variable is used by the UQRTEXT function to select the desired size (in 
world coordinate units) of a character. The pair of values is used to select both 
the width and height of a character. The values must be in the range of 0 to 1 
inclusive. The default value is (0.01 0.01). 

Example: 

DGRCHS I ZE"^. 0625 .0625 
DCRCHSIZE 
0.625 0.625 
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DQRCHSIZE 
Variable (Character Size) 
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UGRCHPLANE Variable (Character Plane) 



Syntax: 

\yiRCHPLANE<-HNN 



Parameters: 

HNH is a simple numeric vector of length 3. 



Oescr i pt I on : 

The QGRCHPLAHE variable is used by the UGRTEXT function to select the orientation in 
the world coordinate system of the plane on which the characters will appear. The 
three values contain an X, Y, and Z component. The default value is (0 0 



Example: 

\yjRCHPLANE 

0 2 1 



UGRCHUP Variable (Character Up) 



Syntax: 

n(iRCHUP*-NNN 



Parameters: 

NUN is a simple numeric vector of length 3. 



Descr i pt i on : 

The [y^RCHUP variable is used by the UGRTEXT system function selects the principal up 
direction in the plane on which the characters will appear. The component of USRCHUP 
perpendicular to OQRCHPLANE points up. The value is made up of (X, Y. Z) components. 
The default value is (0 1 0). 



Examp I e : 

UGRCHUP^l .25 
DGRCHUP 

1 0.25 
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UGRCHUP 
Variable (Character Up) 
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UGRCHPATH Mar ]able (Character Path) 



Syntax: 

{y^RCHPATH^KEYWORD 

Parameters: 

KEYWORD is a simple character vector containing one of the keyword values: 
'RIGHT*, 'LEFT*, 'UP', or 'DOUH' . 

Description: 

The UQRCHPATH variable is used by the UGRTEXT function to determine the direction 
within the plane on which the characters will appear. The default value is 'RIGHT'. 

ExampI e: 

DGRCHPATH*-'DOWN' 
DGRCHPATH 

DOWN 



UGRCHSPACE Variable (Character Space) 

Syntax: 

DGRCHSPACE*-lf 

Parameters: 

N is 0 scalar numeric value in the range 0 to 1 . 
Descr i pt i on: 

The UGRCHSPACE variable is used by the QGRTEXT system function to determine 
additional spacing between adjacent characters in a string. The value represents the 
fraction of the QGRCHSIZE attribute. The default value is 0. 

Example: 

UGRCHSPACE^. 02125 
UGRCHSPACE 
0.03125 
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Variable (Character Space) 
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UGRCHJUST Variable (Character Justification) 



Syntax: 

UfiRCHJUST^-KEYWORDS 



Parameters: 

KEYWORDS is c simple character vector containing two keywords separated by a 
blank. The first keyword value must be either 'OFF', 'LEFT', 'RIGHT', or 'CENTER'. 
The second keyword value must be either 'OFF'. 'TOP'. 'BOTTOM', or 'CENTER'. 



Descript ion: 

The UGRCHJUST variable is used by the UGRTEXT system function to determine the mode 
of string justification. It has two components specifying the horizontal and 
vertical justifications. The default value is 'OFF OFF'. 



Examp I e : 

DGRCHJUST<-'LEFT TOP' 
UGRCHJUST 
LEFT TOP 



UORCHPREC Variable (Character Precision) 



Syntax: 

DGRCHPREC^KEYWORD 



Parameters: 

KEYWORD is a simple character vector containing one of the keyword values: 
'STRING', 'CHARACTER', or 'STROKE'. 



Descr i pt i on : 

The UGRCHPREC is used by the DGRTEXT system function to determine the precision of 
the appearance of text output. The default value is 'STRING'. 



Example: 

DGRCHPREC^' STROKE' 
DGRCHPREC 
STROKE 
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Variable 



DGRCHPREC 

(Character Precision) 
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UGRFILL Variable (FiLL Index) 



Syntax: 
Parameters: 

/ is a simple integer scalar value. 
Descript ion: 

The [yiRFILL variable specifies the index used to select the color or intensity used 
to fill the image of a visible polygon. 

Examp I e : 

D!}RFILL*-Z 
DSRFILL 

3 

UGRVERTEX Variable (Vertex Indices) 

Syntax: 

DSRVERTEX^-IV 

Parameters : 

IV is 0 simple integer vector containing at least 3 values. 
Descript ion: 

The OJRVERTEX variable Is used by the UORPOLYGON function to specify the set of index 
values used to shade the image of a visible polygon (whose [yiRPINS is * SHADED* ) . The 
default value is (1 1 1). 

Example: 

QGRVERTEX^-Z 2 1 5 
UGRVERTEX 
3 2 14 5 
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DQRVERTEX 
Variable (Vertex Indices) 
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Graphics Vieuiing Variables 



APL graphics provides system variables to define the viewing operations and the 
coordinate transformations to be made when graphics output is generated. These 
system variables may be referenced to obtain their current value, assigned to modify 
their value or localized within user-defined functions. The most recently specified 
values of the viewing parameters (or their defaults) are used to determine the 
viewing. 

Viewing parameters may not be specified while a graphics segment is open (or being 
created). If the termination of a defined function causes a viewing variable to be 
surfaced while a segment is open, then the surfaced value is lost. 

The valid values of o viewing variable moy depend on whether the graphics system is 
initialized as 2D or 3D. At graphics initialization time, all values of graphics 
viewing variables are respecified and set to their defaults. 



UGRWINDOW Variable (Window) 



Syntax: 

UdRWINDOW^HUNH 



Parameters: 

tflflfH is a simple numeric vector of length 4. 



Descr i pt i on: 

The UGRWINDOW variable specifies a rectangle in world coordinates. The values define 
the X-minimum, X-maximum, Y— minimum, and Y-maximum extents of the window. The 
default window is (0 1 0 1). 



Examp I e : 

UGRWINDOW^Q .75 .25 1 
UGRWIMDOW 
0 0.75 0.25 1 



Possible Errors: 

A RAHK ERR is reported if: 

o the assigned value is not a vector. 

A LENGTH ERR is reported if: 

o the assigned value is not of length 4 

A DOMAIN ERR is reported If: 

o the assigned value Is not simple or all numeric 

o a segment is currently open 

o the first item is greater than the second or 

the third item is greater than the fourth 
o APL graphics is not initialized 
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DGRWINDOV Variable (Window) 
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UGRUP Variable (View Up) 



Syntax: 



Parameters: 

H23 is a simple numeric vector of 2 items for 2D graphics or 3 items for 3D 
graphics. 



Descr ipt ion: 

The UGRUP variable defines the world coordinate up direction so that the world 
coordinate Y— axis need not be upright on the view surface. The default value for 2D 
graphics is (0 1) and (0 1 0) for 3D graphics. 



Example: 

DCRUP 

1 0 



Possible Errors: 

A RAUK ERR is reported if: 

o the assigned value is not a vector 

A LENGTH ERR is reported if: 

o the assigned value is not of length 2 or 3 
A DOMAIN ERR is reported if: 

o the assigned value is not simple or all numeric 
o APL graphics is not initialized 
o a segment is currently open 
o ol I assigned values are zero 



UGRSPACE Variable (NDC Space) 



Syntax: 

DGRSPACE<-NZ3 

Parometers: 

N23 is a simple numeric vector of 2 items for 2D graphics or 3 items for 3D 
graphics. 
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Descr ipt ion: 

The UGRSPACE variable defines the size of the normalized device coordinate space 
which can be addressed on the view surface of all display devices and within which 
viewports are specified. All values must be in the range 0 to 1 inclusive and at 
least one value must be 1. This value may be specified at most once per 
initialization. The default value for 2D is (1 1) and (1 1 0) for 3D graphics. 



Example: 

Dl}RSPACE 

1 1 



Possible Errors: 

A RAtfK ERR is reported if: 

o the assigned value is not a vector 

A LENGTH ERR is reported if: 

o' the assigned value is not 2 or 3 items in length 
A DOMAIN ERR is reported if: 

o the assigned value is not simple or not oil numeric 

o APL graphics is not initialized 

o the NDC space is already established 

o a value is not in the range of 0 to 1 

o ne i ther va I ue i s 1 

o the first or second value is 0 



UGRVIEWPORT Variable (Viewport) 



Syntax : 

DGRVIEWPORTt-NNNN 



Parameters: 

NNNN is a simple numeric vector of length 4. 



Descript ion: 

The QQRVIEWPORT voriobie specifies a rectangle in normalized device coordinate space. 
The viewport cannot exceed the bounds defined for the variable UGRSPACE. The values 
define (in order) the X-minimum. X-fliaximum, Y-minimum. and Y-maximum limits of the 
viewport. The default value of this variable is the value of [XiRSPACE. 



Examp I e : 

QGRV1EWP0RT<-.IZ5 .875 0 1 
UGRVIEWPORT 
0.125 0.875 0 1 



15-32 



UGRVIEWPORT 
Variable (Viewport) 



CE38-04 



Possible Errors: 

A RANK ERR is reported if: 

o the assigned value is not a vector 

A LENGTH ERR is reported if: 

o the assigned value is not of length 4 

A DOMAIN ERR is reported if: 

o the assigned value is not simple or all numeric 
o APL graphics is not initialized 
o a segment is open 

o the first item Is greater than the second item or 

the third item is greater than the fourth item 
o the viewport is outside of NDC space 



UGRVREFPT Variable (View Reference Point) 

Syntax: 

UGRVREFPT^NNN 

Parameters: 

NNN is a simple numeric vector of length 3. 
Descript ion: 

The [y^RVREFPT variable specifies the view reference point in world coordinates. The 
value specified defines (in order) the X, Y, and Z location of the reference point. 
The default value is (0 0 0). This value is only used in 3D viewing. 

Example: 

UGRVREFPTt-l 2 3 
UGRVREFPT 

1 2 3 

Possible Errors: 

A RANK ERR is reported if: 

o the assigned value is not a vector 

A LENGTH ERR is reported if: 

o the assigned value is not 3 items in length 
A DOMAIN ERR is reported if: 

o the assigned value is not simple or all numeric 
o APL graphics is not initialized 
o a segment is open 
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UGRVPLNORM Variable (View Plane Normal) 



Syntax: 



Parameters: 



NNN 



is a simple numeric vector of length 3. 



Descr i pt Ion: 

The UGRVPLHORH variable specifies the view plane normal. The value specified 
determines a vector in world coordinates relative to the view reference point. The 
value specified defines (in order) the X» Y. and Z location of the view plane normal. 
The default value is (0 0 -1). This value is only used in 3D viewing. 



ExampI e: 

UQRVPLHORMf-l 0 1 
D(}RVPLlfORM 

1 0 1 



Possible Errors: 

A RANK ERR is reported if: 

o the assigned value is not a vector 

A LENGTH ERR is reported if: 

o the assigned value is not of length 3 

A DOMAIN ERR is reported if: 

o the assigned value is not simple or all numeric 
o APL graphics is not initialized 
o all three values are zero 



UGRVPLNDIS Variable (View Plane Distance) 



Syntax: 



DGRVPLNDIS<-N 



Parameters: 



N 



is a simple numeric scalar value. 
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Descript ion: 

The [y^RVPLIfDIS variable specifies the distance of the view plane. The default value 
is 0 which signifies that the view plane is located at the view reference point. 

Example: 

U(^RVPLNDISf2 
\yiRVPLNDIS 

2 

Possible Errors: 

A LEHGTH ERR is reported if: 

o the assigned value is not exactly one item 
k DOMAIN ERR is reported if: 

o the assigned value is not simple or numeric 
o APL graphics is not initiolized 
o 0 segment is open 

UGRVDEPTH Variable (View Depth) 

Syntax: 

DGRVDEPTH*-lfN 

Parameters: 

NN is a simple numeric vector of length 2. 

Description: 

The UGRVDEPTH variable specifies the clipping depth planes but does not affect 
whether depth clipping is performed. The first item is the front distance from the 
view reference point. The second item is the bock distance from the view reference 
point. The default value is (0 -I). 

Examp I e : 

DGRVDEPTH-t-'Z 2 
DGRVDEPTH 

"2 2 

Possible Errors: 

A RAlfK ERR is reported if: 

o the assigned value is not a vector 

A LEHGTH ERR is reported if: 

o the assigned value is not of length 2 
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A DOMAIN ERR is reported if: 

0 the assigned value is not simple or all numeric 
o APL graphics is not initialized 
o a segment is open 

o the first item is greater than or equal to the second 



UGRPROJECT ION Variable (Projection Type) 



Syntax: 

USRPROJECTION^-PROJ 



Parameters : 

PROJ is a 4 item vector. The projection keyword is an enclosed character vector 
representing the first item. The X, Y, and Z positions in world coordinates are the 
final 3 items. The projection keyword value must be either 'PARALLEL* or 
'PERSPECITIVE' . 



Descr i pt i on : 

The UGRPROJECTION variable specifics the type of projection used in the 3D viewing 
operation. If o parallel projection is specified, the world coordinate position 
indicates the lines ore parallel to a line through the view reference point and this 
point. If a perspective projection is selected, the world coordinate position 
specifies the center of the projection. The default value is {* PARALLEL* 0 0 1). 



Ex amp I e : 

UGRPROJECT I ON'*-* PERSPECTIVE* 0 0 2 
DCRPROJECTION 
PERSPECTIVE 0 0 2 



Possible Errors: 

A RANK ERR is reported if: 

o the assigned value is not a vector 

o the first item of the assigned value is not a scalar or a vector 

A LENGTH ERR is reported if: 

o the assigned value is not of length 4 

A DOMAIN ERR is reported if: 

o the first item of the assigned value is not character or the remaining items not 
scalar numbers 

o the first item of the assigned value is not a valid keyword 
o a segment is open 

0 the assigned value is (* PARALLEL* 0 0 0) 
o APL graphics is not initialized 
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Window Clipping Variables 



APL automatically provides a window clipping capability if clipping is enabled. The 
clipping is controlled by specifying values for the three clipping variables: 
DDRCLIP, DGRFCLIP, and USRBCLIP. 



UGRCLIP Variable (Window Clipping) 



Syntax: 



Parameters : 

L specifies a value which can be the simple numeric scalar 0 or 1, or the keyword 
value 'ON' or 'OFF'. 



Descript ion: 

The UGRCLIP variable specifies whether window clipping is enabled. The values 'OH' 
or 1 moy be used to turn window clipping on. The values 'OFF' or 0 may be used to 
turn window clipping off. When referenced, the value is 0 or 1. The default value is 
1. 



Examp I e : 

[yiRCLIP^'OFF' 
DCRCLIP 

0 



Possible Errors: 

A RANK ERR is reported if: 

o the character value assigned is not a scalar or vector 
A LENGTH ERR is reported if: 

o the numeric value assigned is not a singleton 
A DOMAIN ERR is reported if: 

o 0 character value assigned is not a clipping keyword 
0 0 numeric value being assigned is not 0 or 1. 
o APL graphics is not initialized 
0 0 segment is open 
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UGRFCLIP Variable (Front Plane Clipping) 



Syntax: 
Parameters: 

L specifies a value which can be the simple numeric scalar 0 or 1 , or the keyword 
value 'OAT' or '0/"/". 

Descript ion: 

The UGRFCLIP variable specifies whether front plane clipping is enabled. The values 
•OA^' or 1 may be used to turn front plane clipping on. The values 'OFF' or 0 may be 
used to turn front plane clipping off. When referenced, the value is 0 or 1. The 
default value is 0. 



ExampI e: 

UGRFCLIP'f-O 
UGRFCL IP 

0 

Possible Errors: 

A RANK ERR is reported if: 

o the character value assigned is not a scalar or vector 
A LENGTH ERR is reported if: 

o the numeric value assigned is not a singleton 
A DOMAIN ERR is reported if: 

o a character value assigned is not a clipping keyword 
o a numeric value being assigned is not 0 or 1 
o APL graphics is not initialized 
o a segment is open 

UGRBCLIP Variable (Back Plane Clipping) 

Syntax: 

DGRBCLIP^-L 

Parameters: 

L specifies a value which can be the simple numeric scalar 0 or 1 , or the keyword 
value 'OH' or 'OFF'. 
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Descr ipt ion: 

The UGRBCLIP variable specifies whether back plane clipping is enabled. The values 
•OA^' or 1 may be used to turn bock plane clipping on. The values 'OFF' or 0 may be 
used to turn back plane clipping off. When referenced, the value is 0 or 1. The 
default value is 0. 



Example: 

UQRBCL IP^l 
UHRBCLIP 

1 



Possible Errors: 

A RAHK ERR is reported if: 

o the character value assigned is not a scalar or vector 
A LENGTH ERR is reported if: 

o the numeric value assigned is not a singleton 
A DOMAIN ERR is reported if: 

o a character volue assigned is not a clipping keyword 
o a numeric value being assigned is not 0 or 1 
o APL graphics is not initialized 
o a segment is open 



UORCOORD Variable (Coordinate System Type) 



Syntax: 

BiRCOORD^KEYVORD 



Parameters: 

KEYWORD is o simple character vector containing one of the keyword values: 
*LEFT' or 'RIGHT*. 



Description: 

The UGRCOORD variable is used to specify whether the world coordinate system is 
left-handed or right-handed. The default value is 'RIGHT*. 



Examp I e : 

DGRCOORD 

RIGHT 
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Possible Errors: 

A RANK ERR is reported if: 

o the character value assigned is not a scalar or vector 
A LENGTH ERR is reported if: 

o the numeric value assigned is not a singleton 
A DOMAIN ERR is reported if: 

o a charocter value assigned is not a clipping keyword 
o a numeric value being assigned is not 0 or 1 
o APL graphics is not initialized 
o a segment is open 

UGRWORLD Variable (World Transformation) 



Syntax: 

UGRWORLD^-MAT 

Parameters: 

MAT is a simple numeric matrix of shape (3 3) for 2D transformations or shape (4 

4) for 3D transformations. 

Descr i pt i on : 

The UGRWORLD variable is used to transform world coordinate positions. This matrix 
is used in a matrix multiplication which con effect scaling, translation, and 
rotation of the position. 

Example: 

UGRWORLD 

1 0 0 
0 1 0 
0 0 1 

Possible Errors: 

A RANK ERR is reported if: 

o the value assigned is not a matrix 

A LENGTH ERR is reported if: 

o the value assigned Is not shape 3— by— 3 or shape 4-by— 4 
A DOMAIN ERR is reported if: 

o the value assigned is not simple and all numeric 
o APL graphics is not initialized 
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Graphics Control Functions and Variables 



CP-6 APL provides several functions and variables which control the picture 
generation process. These capabilities are provided for: 



o Initiating and terminating APL graphics 

o View surface (device) control 

o Picture change control 

o Frame control 

o Color spec i f i cot i on 

o Color and intensity binding 

o Pixel array definition 



Before graphics output can occur, APL graphics must be initialized and a view surface 
must be initialized and selected. 



UGRINIT Function (Initialize APL Graphics) 



Syntax: 

□C/Z/A^/r STRING 



Parameters : 



STRING is o simple character vector containing initial ization keywords separated 

by blanks or a single comma. Any keyword that is all blank is defaulted. 



Desc r i pt I on : 

The UGRINIT function is used to initialize APL graphics. The right argument may 
contain up to four keywords which define (in order) the graphics output level, the 
input level, the number of dimensions, and the hidden surface removal level. The 
values for output level are: 'BASIC, 'BUFFERED', ' DYNAMIC-A' , ' DYNAMIC-B' , and 
'DYNAMIC-C' . The value for the input level is: 'NONE'. The values for the number of 
dimensions ore: *2D' or '3D'. The value for the hidden surface removal level is: 
'NONE' . 



This function must be executed before any other graphics function is executed or any 
graphics variable is referenced or assigned. It causes all graphics variables to be 
initialized to their default values. 



Example: 

DGRINIT 'BUFFERED,, ZD' 



In this example, APL graphics is initialized with the output level 'BUFFERED' , the 

input level 'NONE', a dimensionality of '2D', and a hidden surface removal level of 

'NONE'. The default right argument (if on empty or all blank value is specified) is 
• BUFFERED , NONE , ZD , NONE ' . 



Possible Errors: 

A RANK ERR is reported if: 

o the right argument is not a vector or scalar 
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A DOMAIN ERR is reported if: 



o Graphics is already initialized 

o the output level is not supported 

o the input level is not supported 

o the dimension level is not supported 

o the hidden surface level is not supported 

o an undefined keyword is provided 

o too many keywords are provided 

o APL graphics capability is not available 



UGRDONE Function (Terminate APL Graphics) 



Syntax: 

DdRDONE 



Descr i pt i on : 

The [JQRDONE function closes any open segments, terminates all initialized view 
surfaces, and releases all resources used by APL graphics. After this function is 
executed, APL graphics may be reinitialized by executing the [XiRINIT function. 



Example: 

DSRDONE 



Possible Errors: 

A DOMAIN ERR is reported if: 

o APL graphics is not initialized 



UGRINITSURF Function (Initialize View Surface) 



Syntax: 

STRING USRINITSURF SURF 



Parameters: 

STRING is a simple character vector containing options separated by commas. 
SURF is a simple integer scalar indicating a view surface number. 



Description: 

The UGRINITSURF function obtains access to the specified view surface and clears it. 
The right argument is a view surface number. The left argument specifies attributes 
of the view surface. The left argument is composed of the keyword * INTENSITY^ or 
^ COLOR' , followed by the CP-6 fid indicating the location of the view surface 
(default is *ME*). This is followed by the CP-6 device profile name (default is 
current profile if online or super-graphics device if batch). Each of these 
parameters is separated by blanks or commas. The default left argument (if it is 
empty) is ' INTENSITY , ME' . 
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Example: 

'INTENSITY' USRINITSURF 1 

In this case, the view surface is cleared and the device is prepared for graphics 
output on the terminal. 

Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a scalar or vector 
A LENGTH ERR is reported if: 

o the right argument contains more than one item 

A DOMAIN ERR is reported if: 

0 the view surface is already initialized 

o all possible view surfaces are initialized 

o an unknown keyword value is specified 

o color is not provided on this surface 

o the left argument is not all character scalar items 

o the right argument is not on integer scalar 

o too many keywords in the left argument 

UGRTERMSURF Function (Terminate View Surface) 

Syntax : 

UGRTERMSURF SURFS 

Parameters: 

SURFS is a simple integer vector of view surface numbers. 
Descript ion: 

The UGRTERMSURF function terminates access to the view surface. Segments whose 
images appear only on this view surface are deleted. 

Example: 

UGRTERMSURF 1 

In this cose, the view surface number 1 is terminated. 

Possible Errors: 

A RANK ERR is reported if: 

o the right argument is not a scalar or vector 

A DOMAIN ERR is reported if: 

o the view surface is not initialized 

o APL graphics is not initialized 

o an item of the right argument is not an integer 
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UGRCAP ABILITIES Function (Inquire Capabilities) 



Syntax: 

CAP*-D(iRCAP ABILITIES SURF 

Parameters: 

SURF is a simple integer scalar indicating a view surface number. 
CAP is a 6— item nested array indicating the device capabilities. 

Descr i pt i on: 

The UQRCAPABILITIES function returns the device capabilities associated with the 
specified view surface. Each item of the result indicates attributes of the device. 
They are separated into 6 classes of information which ore: 

1 the highest initialization levels supported by the device. 

2 an indication of whether the device is physically there or is a pseudo device. 

3 the size of the view surface (in centimeters). 

4 the level of support available for the primitive attributes. 

5 an indication of how the segment attributes are supported. 

6 an indication of the effect of batching functions. 
The result is a 6 item vector containing: 

1 . LEVELS 

A 3 item nested vector containing three character vectors: 

1 highest output level supported 

2 highest dimension level supported 

3 highest hidden surface level supported 

2. PHYSICAL 

A character vector containing the value 'PSEUDO' or 
•REAL'. 

3. SIZES 

A 6 item numeric vector containing: 

1-2 width and height of view surface in centimeters 
3-4 width and height of NDC space area in centimeters 
5-6 horizontal and vertical resolution per centimeter 

4. PRIMITIVE_ATTRIBUTES 

A 22 item numeric vector containing: 

1 Line index color count 

2 Line index intensity count 

3 Line index global color count 

4 Line index global intensity count 

5 Line index intensity hard/soft 

6 Line index color type 

7 Line index intensity type 

8 Line style hardware count 
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9 Line style software count 

10 Line width count 

11 Line width hard/soft 

12 Line width minimum NDC 

13 Line width maximum NDC 

14 PEN hardware count 

15 PEN software count 

16 FONT count 

17 Charsize count 

18 Charsize hard/soft 

19 Charsize minimum size in NDC 

20 Charsize maximum size in NDC 

21 Marker hardware count 

22 Marker software count 

5. SEGMENT_ATTRIBUTES 

A vector containing two character vectors: 

1 highlighting support 

2 image transformation support 

6. BATCHING 

A character vector indicating the strategy used by the 
device for batching of updates. 



ExampI e: 

qCAP*^RCAP ABILITIES 1 



Possible Errors: 

A LENOTH ERR is reported if: 

o the right argument is not a single value 

A DOMAIN ERR is reported if: 

o the right argument value is not an integer 

o the right argument value is not a valid view surface 

o APL Graphics is not initialized 



UGRSURFACE Function (Select View Surface) 



Syntax: 

USRSURFACE SURFS 



Parameters: 

SURFS is a simple integer vector of view surface numbers. 
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Function (Select View Surface) 



Descr ipt ion: 

The UQRSURFACE function odds the specified view surfaces to the list of currently 
selected view surfoces. When a subsequent segment is created, the graphics output 
will appear only on those surfaces that are currently selected. 

Example: 

QGRSURFACE 1 
This example selects view surface 1. 

Possible Errors: 

A RANK ERR is reported if: 

o the right argument is not a scalar or vector 
A DOMAIH ERR is reported if: 

o the right argument values are not integer 
o o segment is currently open 

o the specified view surfoce is not initiolized 
o the specified view surface has been selected 
o APL Graphics is not initialized 

UGRUNSURFACE Function (Deselect View Surface) 

Syntax : 

UGRUNSURFACE SURFS 

Parameters: 

SURFS is a simple integer vector of view surface numbers. 
Descript ion: 

The []ORUNSURFACE function removes the view surface specified from the set of selected 
view surfaces. Subsequent segment creations and DdRFRAME function execution will not 
affect this view surface until it is reselected. 

Exomp I e : 

USRUNSURFACE 1 
This example deselects view surface 1. 

Possible Errors: 

A RANK ERR is reported if: 

o the right argument is not a scalar or vector 
A DOMAIN ERR is reported if: 

o the right argument contains a non-integer value 
o a segment is open 

o the view surface has not been selected 
o APL Graphics is not initialized 
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UGRSURFACES Function (Inquire Selected Surfaces) 



Syntax: 

SURFS*-DSRSURFACES 

Parameters: 

SURFS is a simple integer vector of view surface numbers. 

Descr ipt ion: 

The UCRSURFACE function returns a vector containing the numbers of the selected view 
surfaces. 

Examp I e : 

UGRSURFACES 

1 

In this example, the result is the vector 1 indicating that view surface 1 has been 
selected. 

Possible Errors: 

A DOMAIN ERR is reported if: 

o APL graphics is not initialized 

UGRIMMVISIBILITY Function (Immediate Visibility) 

Syntax: 

UGRIMMVISIBILITY LOGL 

Parameters: 

LOGL is the simple scalar number 0 or 1 . Optionally, the keyword 'OV or *OFF* 
may be used. 

Description: 

Specifying the value 1 as the right argument causes all delayed visible picture 
changes to take effect unless they are deferred as a result of batching. 

Example: 

UGRIMMVISIBILITY 1 
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Possible Errors: 

A RANK ERR is reported if: 

o the right argument is character and is not a scalar or vector 
A LENGTH ERR is reported if: 

o the right argument is numeric and contains more than one item 
A DOMAIN ERR is reported if: 

o the right argument is not the number 0 or 1 or the character vector is not 'OiV' 
or 'OFF'. 

o APL graphics is not initialized 

UGRCURRENT Function (Make Picture Current) 

Syntax: 

UGRCURRENT 

Description: 

The UGRCURRENT function has no effect if Immediate visibility Is 1. If Immediate 
visibility is 0. all delayed visible picture changes take effect subject to batching. 

Example: 

UGRCURRENT 

Possible Errors: 

A DOMAIN ERR is reported If: 

o APL graphics Is not initialized 

UORBATCH Function (Control Batching of Updates) 

Syntax: 

UGRBATCH LOGL 

Parameters: 

LOGL is the simple numeric scalar value 0 or 1 . 
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Descript ion: 



If the right argument is 1. a batch of updates is started. The end of the batch of 
updates is indicated by executing the \yjRBATCH function with a right argument value 
of 0. While batching of updates is in effect, visible picture changes are deferred 



Example: 

^CRBATCH 1 

UGRLINE 7 2p .1 .6 .5 .9 .6 .9 .1 .9 .1 .1 .6 .1 .6 .9 
DCRBATCH 0 



Possible Errors: 

A LENGTH ERR is reported if: 

o the right argument contains more than one item 

A DOHAIH ERR is reported if: 

o the right argument value is not 0 or 1 

o APL graphics is not initialized 

o the right argument value is 1 and already batching updates 

o the right argument value is 0 and not batching updates 



UGRCSTATUS Function (Inquire Control Status) 



Syntax: 

L0GL2*BC;RCSTATUS 



Parameters: 

LOGLZ is a simple vector of 2 items containing the values 0 or 1 . 



Description: 

The UGRSTATUS function indicates the current status of immediacy and batching of 
updates. The first item is 1 if updates are immediately visible, otherwise it is 0. 
The second item is 1 if within a batch of updates, otherwise it is 0. 



Examp I e : 

UGRCSTATUS 

1 0 

This result indicates that immediate visibility is in effect and thot no batching of 
updates is being performed. 



Possible Errors: 

A DOMAIN ERR is reported if: 

o APL graphics is not initialized 
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UGRFRAME Function (New Frame) 



Syntax: 

USRFRAHE 

Descript ion: 

The DQRFRAME function causes a new frame action to occur. The result on each 
affected view surface is that the surface is erased and all visible retained segments 
ore redrawn. 

Possible Errors: 

A DOMAIN ERR is reported if: 

o the set of currently selected view surfaces is empty 
o APL graphics is not initialized 

UGRCOLMODEL Function (Color Model) 

Syntax: 

WRCOLHODEL KEY 

Parameters: 

KEY is a simple character vector containing the keyword value *HLS' , 'RGB' or 
Description: 

The UGRCOLMODEL function is used to establish or Inquire about the current color 
model. If the right argument is empty or contains only blanks, the result is the 
current color model type (.'RGB' or 'HLS'). If the right argument contains non-blank 
characters, they are used to specify the color model. The color model may be 
established once after APL graphics is initialized before any view surfaces ore 
initial ized. 

Example: 

UGRCOLMODEL " 

HLS 

This example demonstrates obtaining the current color model. 

Possible Errors: 

A RAtfK ERR is reported if: 

o the right argument is not a scalar or vector. 
A DOMAIN ERR is reported if: 

o the keyword specified is not 'RGB' or 'HLS' 

o a keyword is specified and a view surface has been initialized 
o APL graphics is not initialized 
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UGRCOLIMDEX Function (Set/Inquire Color Indices) 



Syntax : 

COLSf-COLS UGRCOL INDEX SURF 
COLS'*- QGRCOLIHDEX SURF 



Parameters: 

SURF is a simple integer scalar indicating a view surface number. 
COLS is a simple N-by-3 numeric array whose values range from 0 to 1 . 



Descr i pt i on : 

Dyadically, the UORCOLINDEX function sets oil of the color entries for the specified 
view surface to the color components specified by the left argument and returns an 
empty vector. Monadically, the UGRCOLINDEX function returns the currently defined 
color entries for the specified view surface. 



Example: 

(4 3p 0 0 1 0 1 0 1 0 0 1 1 1) DURCOLIHDEX 1 
UGRCOL INDEX 1 

0 0 1 

0 1 0 

1 0 0 
1 1 1 



Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a matrix 

A LENGTH ERR is reported if: 

o the right argument is not exactly one item 

o the second dimension of the left argument is not 3 

A DOMAIN ERR is reported if: 

o the right argument is not an integer 

o the left argument is not numeric 

o the specified view surface is not initialized 

o the view surface is not of type * COLOR* 

o too many indices are specified 

o one or more of the color parameters is invalid 

o APL graphics is not initialized 
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UGRINT INDEX Function (Set/Inquire Intensity Indices) 



Syntax: 



INTS^-INTS UGRItfTIHDEX SURF 



IHTS*- 



[yiRINTIHDEX SURF 



Parameters: 



SURF 



is a simple integer scalar indicating a view surface number. 



IHTS 



is a simple numeric vector whose values range from 0 to 1 . 



Description: 

Dyadically. the [yiRIHTINDEX function sets all of the i\ntensity entries for the 
specified view surface to the intensity values specified by the left argument and 
returns an empty vector. Monadically, the UHRINTIHDEX function returns the currently 
defined intensity entries for the specified view surface. 



Examp I e : 

.1 .2 .3 .4 .5 .6 .7 UGRINT INDEX 1 
DCRCOL INDEX 1 
O.l 0.2 0.3 O.k 0.5 0.6 0.7 



Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a vector or scalar 
A LENGTH ERR is reported if: 

o the right argument is not exactly one item 

A DOMAIN ERR is reported if: 

o the right argument is not on integer 

o the left argument is not numeric 

o the specified view surface is not initialized 

o the view surface is not of type 'INTENSITY' 

o too many indices are specified 

o one or more of the intensity values are invalid 

o APL graphics is not initialized 



15-52 



\yiRINTINDEX 
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UGRBACKGROUND Variable (Background Index) 



Syntax: 

DGRBACKGROUND^-I 

Parameters: 

/ is a simple integer scalar. 
Description: 

The UGRBACKGROUHD variable controls the current bockground index. During a new-frame 
action, the background is set to the color or intensity specified by the value of 
this variable. 

Examp I e : 

UGRBACKGROUHD^ I 
UGRBACKGROUND 

1 

Possible Errors: 

A LENGTH ERR is reported if: 

o the volue being assigned contains more than one item 
A DOMAIN ERR is reported if: 

o the specified index value is not supported by a view surface 
o APL graphics is not initialized 

UGRPIXEL Variable (Pixel Array) 

Syntax: 

UGRPIXEL'^MAT 

Parameters: 

HAT is a simple integer matrix. 
Description: 

The UQRPIXEL variable specifies the pixel array that is used when a polygon is drawn, 
and the UGRPINS variable has the value * PATTERNED^. 
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UGRPIXEL 
Variable (Pixel Array) 
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Example: 



DC^RPIXEL^Z 2p 2 3 1 * 
DGRPIXEL 

2 3 
1 k 



Possible Errors: 

A RANK ERR Is reported if: 

o the assigned value is not a matrix 

A DOMAIN ERR is reported if: 

o the matrix is too large 

o the matrix is empty 

o APL graphics is not initialized 



UGRPIXELORG Variable (Pixel Pattern Origin) 



Syntax : 

DQRPIXELORG^XY 



Parameters: 

XY is a simple 2 item vector containing a position in normalized device 
coordinate space. The default value is 0 0. 



Description: 

The []SRPIXELORG variable is used to specify the origin for the transfer of the pixel 
array to the view surface. The origin specifies the position of the item in the 
lower left-hand corner of the current pixel array. 



Examp I e : 

[}GRPIXEL0RG^0.Z5 0.125 
DGRPIXELORG 
0.25 0.125 



Possible Errors: 

A RANK ERR is reported if: 

o the assigned value is not a vector 

A LENGTH ERR is reported if: 

o the assigned value is not exactly 2 items 

A DOMAIN ERR is reported if: 

o the value specified is outside of NDC space 
o the value specified is not numeric 
o APL graphics is not initialized 
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DGRPIXELORG 
Variable (Pixel Pattern Origin) 
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Section 16 
Blind I/O 



Blind I/O is a capability which is of use in a number of specialized cases. The 
major uses of blind I/O include: 

o Sending or receiving data to CP-6 devices or files without undergoing any 
translation or validity checking by APL. 

o Exercising more control over a CP-6 device than is possible with normal APL input 
and output. 

o Accessing multiple input and output streams (or devices) simultaneously. 

o Creating a terminal independent CP-6 FORM which permits reading, writing and 
clearing specified fields In a screen-oriented fashion. 

For example, blind input permits the entry of overstrikes (or any other characters) 
which would result in a BAD CHAR error if normal APL input were used. Blind output 
may be used to output special character sequences (including ASCII control 
characters) to perform special device functions such as controlling a plotter. 



Using Bl ind I/O 

APL provides ten DCBs - F$Q0 through F$Q9 to be used for blind I/O, but performs no 
special set-up on them. It is assumed that the DOB will be assigned to devices or 
files, using the )SET command (section 8). If a )SET command has not been issued, 
the blind I/O streams default to the standard APL input (and output) streams (the 
CP— 6 ME device, which is the terminal if online or the card— reader if batch). 

Within APL, the characters Q through Q (quad overstruck with 0 through 9) supplement 
the quad and quote— quad characters. They are used to access the DCBs when blind 
input or output is desired. 

There is no limit on the size of a record input via blind I/O. Input from blind DCBs 
creates a character vector result. If the data actually contains logic values, 
integer values, or floating point values, then the UCVT function may be used to 
correct the data type after input. 

Blind output may only be used to output simple APL arrays. It should be noted, 
however, that large output records routed to physical devices with maximum length 
constraints will be truncated on output. In particular, records output to the user's 
console should be limited to 511 bytes, and records output to a line printer to 132 
bytes. Note also that blind output of non-character data to a printing device may 
lead to unpredictable results. 

APL bypasses all of its translation sequences (overstrike resolution and mnemonic 
substitution) for blind input. If an end-of-file condition is encountered by a 
blind-input request, APL returns an empty numeric vector result. 
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Bl ind I/O on a Device 



In the following examples, B is ossigned to the user's console (if the session is 
online) after calling APL, as follows: 

)SET B HE .ORQ'TERMIHAL .FUU'UPDATE 

Quad-2 may then used for blind input and for blind output to the terminal. In the 
example below, blind input functions much the same as a quote-quad input, since the 
terminal itself is the input device. 

NOV IS THE TIME FOR ALL GOOD MEN. 
A 

NOW IS THE TIME FOR ALL GOOD HEN. 

Blind input can be used to input illegal overstrike characters, which cannot be done 
with quote-quad Input. Note, however, that the characters entered appear in the 
result, including backspaces, and that overstrikes ore not mapped into single APL 
characters. 

The examples below illustrate blind output to the terminal. Only simple arrays 
containing all character or all numeric data may be written with blind I/O. Note 
that the data to be output was specified as a literal. When the RETURN key is 
struck, the data is output the terminal exactly as it was input. 

0<-' l2:iii5eiQ90+>iQNERTYUI0P-*ASDFGHJKLl ]ZXCVBNH , ./• 
lZ3k567Q90^-*QWERTYUIOP*ASDFGHJKL[ ]ZXCVBNH, ./ 

B<-»""<^=S>»<vA-^-?<u€p-t*iO*-»'ori-VAo' 'DOcDnuiTl . :\» 
"~<S=k>/vA-^-?u£p-tiiO*->af L-VAo •□( )cDnuiT| ; :\ 

B*-'ASDF' 

ASDF 

Note that the QBTRANS function may be used to request transparent input. Transparent 
input from a terminal (with ORG=TERMINAL specified on the SET command) should only be 
specified when all of the control characters entered are of interest to the APL 
program. In this mode, the terminal read is not terminated until the number of 
characters specified by the read (511 by default, or see UBSIZE) have been received. 
The command: 

)SET ID HE,FUN=CREATE 

is used to set (D to the terminal (or lineprinter in batch). In this cose, unit 
record oriented functions may be performed on the stream. This includes the ability 
to specify a page heading on the SET command and to use the UBLINES function to 
determine the number of lines per page and the number of lines remaining on the 
current page. The UBVFC function may be used to indicate that the first character of 
each output line is to be used to control line spacing. 

The UTSQZ system function may be used to map legal APL overstrikes and mnemonics into 
their internal representations or to map the internal APL characters into mnemonics 
and overstrikes appropriate for the current APL terminal (as indicated by the current 
terminal type). 
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Accessing Files with Bi ind I/O 



In the following examples, Q] is assigned to a test input file which is built using 
CP-6 EDIT: 

lEDIT 

EDIT C00 HERE 
*BUILD BLINDIN 

1 .000 BLINDIN, RECORD 1 , 

2.000 RECORD 2. TEST BACKSPACING. 

3.000 LAST RECORD 

4.000 
• END 

Record 2 of the file contains a series of blanks and backspaces such that the total 
number of characters in the record is considerably more than the example shows. 

After APL is cal led: 

)SET Q] BLINDIH,FUN=IN 

In the next exomple, blind input is used to input records from the file. Note that 
on attempt to use blind I/O to access the non-existent fourth record results in an 
empty integer vector. 

A, B. C. and D now contain the data from the file records, as shown below. Note that 
the length of B reflects the blanks and backspace characters that were part of the 

file record. 

pA 

18 

A 

BLIND IN. RECORD 1. 
PB 

81 

B 

RECORD 2. TEST BACKSPACING. 
pC 

15 

C 

LAST RECORD. 
PD 

0 

When blind output to a file is used, records are output as character data — scalars, 
vectors, and arrays are written without any sort of header data. 

The blind I/O system functions UBPRECORD, UBPFILE, and UBREW may be used to position 
to a specific record within the file. The system functions UBSEED and UBREWRITE may 
be used to set record encryption or or to indicate that the last record read is to be 
replaced. 

When writing records to a keyed, random or relative file, the record identifier 
(number or key) may be specified by assigning a nested array whose first item is a 
simple non-negative scalar integer less than 134217726 or a simple character vector. 
The second item is a non-scalar array to be written. 

For example: 

IIH-5000 'EDIT KEY FIVE' 

fa*-'TEXT KEY' 'RECORD ASSOCIATED WITH KEY ."TEXT KEY'" 
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In the first example, the integer key 5000 is used to write the record. In the 
second statement, the character key 'TEXT KEY' is used to write the record. Note 
that blind I/O does not permit records to be read by their key as does APL File I/O 
(see Section 12). 



Blind I/O System Functions 

CP-6 APL allows options to be specified for reading and writing with blind I/O. 
These capabilities include specification and interrogation of VFC. TRANSPARENCY and 
BINARY modes, setting the encryption seed for reading and writing, and setting the 
size of the record to read. 

The right argument to the blind I/O system functions must be a scalar or vector or a 
RANK ERR is reported. If a vector argument is provided, there must be one or two 
items or a LENGTH ERR is reported. The right argument must be simple and contain 
only scalar integers or a DOMAIN ERR is reported. 

When 0 scalar or one-item vector argument is provided, the current status of an I/O 
option is returned. When a two item vector argument is provided, the I/O option is 
set for a subsequent read or write. The first item of the argument is the blind I/O 
stream number to be affected. 



UBBIN Function (Set and Query Binary Mode) 



Syntax: 

I*-UBBIN N,L 



Parameters : 

N is a simple integer scalar representing the blind I/O channel number. 

L is an optional simple integer scalar value 0 or 1. 
/ is 0 simple integer scalar value 0 or 1. 



Description: 

The UBBIN function sets or resets binary mode. If L is equal to one, then subsequent 
reads and writes through channel N wi I I be in binary mode. If L is zero, then 
subsequent reads end writes will not specify binary mode. If L is not present, the 
result indicates whether the last operation was BINARY. 

When querying binary mode, this function indicates whether the last record read or 
written was with BINARY. 
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UBBIN 

Function (Set and Query Binary Mode) 
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UBSIZE Function (Read Size) 



Syntax : 

I^UBSIZE N.I 



Parameters: 

is a simple integer scalar representing the blind I/O channel number. 
/ is an optional simple integer scalar value greater than or equal to 0. 



Descript ion: 

When a blind I/O stream is SET or opened for the first time, APL determines a default 
read size that is sufficient for any record in the file. This function is used to 
override the default input record size. The integer value I is subsequently used for 
the record size. If / is zero, then APL reverts back to the default read size for 
the stream. If / is not specified in the right argument, the result is the current 
default read record size; otherwise, an empty vector is returned. 



UBVFC Function (Set and Query VFC) 



Syntax : 

I'>-UBVFC N.L 

Parameters: 

N is a simple integer scalar representing the blind I/O channel number. 
L is an optional simple integer scalar value 0 or 1 . 
/ is the simple integer scalar value 0 or 1. 

Descript ion: 

If L is net present, then this function indicates whether the last record read was 
originally written with VFC. 

If L is one, subsequent writes through channel wi I I specify VFC. If L is zero, 
then subsequent writes will not specify VFC. 
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UBVFC 

Function (Set and Query VFC) 
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UBTRANS Function (Set and Query Transparency) 



Syntax: 

I^UBTRAHS N.L 

Parameters: 

N is a simple integer scalar representing the blind I/O channel number. 

/ is the simple integer scalar value 0 or 1. 

L is an optional simple integer scalar value 0 or 1. 

Description: 

If L Is not present, then this function indicates whether the last record read or 
written was with transparency. 

If L is one, subsequent blind I/O reads and writes through channel wi II specify 
TRANSPARENCY. If L is zero, then subsequent writes will not specify transparency. 

UBLINES Function (Lines Remaining) 

Syntax: 

I*OBLINES N 

Parameters: 

N is a simple integer scalar representing the blind I/O channel number. 
/ ISO simple 2-item integer vector. 

Descr ipt ion: 

This function returns a two item integer vector containing the number of lines per 
page, and the number of lines currently remaining on the page printed through channel 
N. 

UBKEY Function (Return Key) 

Syntax: 

K*{\BKEr N 
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Parameters: 

N is a simple integer scalar representing the blind I/O channel number. 
K is a record key returned as an integer or character vector. 



Descr i pt i on : 

The result is the key of the next record to be read, or, if the file is not keyed or 
indexed, the record number of the next record to be read. Three byte keys and record 
numbers are returned as integers, all other keys are returned as character vectors. 
This function operates on tape or disk files only. 



UBPRECORD Function (Position Record) 



Syntax: 

K*-UBPRECORD N,I 

Parameters: 

is a simple integer scalar representing the blind I/O channel number. 
/ is a simple integer scalar. 

K is 0 record key returned as an integer or character vector. 

Descript ion: 

If / is positive, the file or device is positioned / records ahead. If / is 
negative, the file or device is backspaced / records. The result is the key of the 
record positioned to (or record number for sequential files). 



UBPFILE Function (Position File) 



Syntax: 

UBPFILE N,L 

Parameters: 

If is a simple integer scalar representing the blind I/O channel number. 
L is a simple integer scalar. 

Descr ipt ion: 

If L is zero, then the file or device is positioned to the beginning of the file. If 
L is one, then the file or device is positioned to the end of the file. 
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UBPFILE 
Function (Position File) 
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UBREW Function (Rewind) 



Syntax: 

UBREW N 

Parameters: 

is a simple integer scalar representing the blind I/O channel number. 
Descript ion: 

The file associated with stream N is positioned to the beginning of file or the 
device associated with stream N is rewound. 

UBREWRITE Function (Rewrite Record) 

Syntax : 

UBREWRITE N,L 

Parameters: 

H is a simple integer scalar representing the blind I/O channel number. 
L is a simple integer scalar. 

Descript ion: 

If L is one, then subsequent writes will specify the REWRITE option. If L is zero, 
then the REWRITE option is not specified. If L is not specified, the result is the 
current setting of rewrite for this streom. 

UBSEED Function (Encryption Seed) 

Syntax: 

UBSEED N,I 

Parameters: 

H is a simple Integer scalar representing the blind I/O channel number. 
/ is a simple Integer scalar. 
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UBSEED 

Function (Encryption Seed) 
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Descri pt ion: 

The integer value / is used on all succeeding reads and writes as the encryption seed 
for channel N. 



UBRR Function (Re-Read Mode) 



Syntax: 

R^UBRR rv 



Parameters: 

IV is 0 simple 1 or 2— item integer vector containing as the first item a blind 
I/O stream number. The second item must be the value 0 or 1. 

R ISO simple integer scalar containing the previous re-read setting. 



Description: 

The UBRR function permits the spec i f i cot i on of re-read on blind input for each blind 
I/O stream. This function may be used in conjunction with the UTTIN system function 
which sets the re-read line. If the second item of IV is not present, then the 
result indicates whether re-read will be specified on the next read. If the second 
item of IV is 1, re— read will be specified on the next read. If the second item of 
IV is 0, then re-read will not be specified on the next read. 



UBRS Function (Record Size) 



Syntax: 

R*UBRS I 



Parameters: 

/ is a simple integer scalar containing a blind I/O stream number. 

R is o simple integer scalar representing the value of the ARS| field of the DCB 
associated with the specified stream. 



Description: 

The UBRS system function is used to return the setting of the DCB field F$DCB.ARS#. 

This is intended to be used with screen edit access mode which provides information 
via this DCB field. 
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UBRS Function (Record Size) 
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UBKR Function (Key Returned) 



Syntax: 

R*-UBKR I 

Parameters: 

/ is a simple integer scalar whose value is used to indicate a blind I/O stream 
to be affected. 

R is a simple character vector. 
Descript ion: 

The UBKR system function is used to return the key specified by the most recent 
M$READ or M$WRITE associated with a blind I/O stream whose ORG is SE or FORM. 



UBCLOSE Function (Close Blind I/O Channel) 



Syntax: 

UBCLOSE N 
UBCLOSE N,L 

Parameters : 

is a simple integer scalar representing a blind I/O channel number. 
L is a simple integer scalar value 0 or 1. 

Description: 

The UBCLOSE function closes the specified blind I/O channel. If L is 1 or not 
specified, the channel is closed with SAVE. If L is 0, the channel is closed with 
RELEASE. The RELEASE option is used to delete files or make windows created by a )SET 
command disappear. 

If this function is not executed, an automatic close is performed whenever a )SET 
command is issued to a channel, or when the APL session ends. 
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UBCLOSE 

Function (Close Blind I/O Channel) 
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UBPAGE Function (Skip to New Page) 



Syntax: 

UBPAGE If 
UBPAGE N,L 

Parameters: 

is a simple integer scalar representing a blind I/O channel number. 
L is a simple integer scalar value 0 or 1 . 

Descr i pt i on : 

The UBPAGE function is used to eject the current page of o unit record device. 

If the blind I/O channel is open to the terminal with ORG=FORM, the argument L is 
used to control the display. For screens, if L=0, then this function causes the 
screen to be updated. If the device is not a screen and L^O, then nothing is 
printed. If , then the screen is updated or the form is printed. 



UBDELREC Function (Delete Record) 



Syntax: 

UBDELREC H 
UBDELREC H,Kl 
UBDELREC H.Kl.KZ 

Parameters: 

tf is a simple integer scalar representing the blind I/O channel number. 
Kl is a simple integer scalar. 
K2 is a simple integer scalar. 

Desc r i pt i on: 

The UBDELREC function is used to delete a record (or records) from a file. If Kl is 
not specified, the last record read or written is deleted. Otherwise, Kl indicates 
the key of the record to delete. If K2 is specified, all records between Kl and K2 
(inclusive) are deleted. 
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UBDELREC 
Function (Delete Record) 
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WNSET Function (Unset DCB) 



Syntax: 

V*WNSET N 



Parameters: 

N is a simple integer scalar representing the blind I/O channel number or a 
simple character scalar or vector. 



Descript ion: 

If N is an integer channel number, the result is o character string containing the 
fid and )SET options for this blind I/O channel. If N is a character vector, the 
result is the setting for the DCB named. 



Forms Mode 



Forms mode is a terminal independent method of defining a screen (form) consisting of 
a number of fields and accessing specific fields for the purpose of reading, writing 
and erasing. In forms mode, a field is o variable length string of characters which 
are on a specific line, start in a specific column and occupy N columns (where N is 
the length of the field). Multiple fields may appear on the same line, but fields 
may not overlap. Forms mode permits form definition, field selection, field input, 
field output and selective erasure. 

When 0 blind I/O channel is open with ORG=FORM, the result of a read and the value to 
write is a matrix of two columns. The first column is on integer key or field 
number. The second column contains enclosed character vectors. 

When forms mode is required, the blind I/O channel that is used should be )SET to the 
terminal with the option ORG=F0RM. If a CRT terminal is in use, a window for the form 
should also be defined with the WWIDTH= and WLENGTH= options. Next, the fields for 
that form must be defined by executing the UBFLD system function. This system 
function defines the position, length, initial contents, and attributes of the fields 
on the screen. Attributes and contents of currently defined screen fields can be 
modified by the UBHFLD system function. 

Before reading from on ORG=FORM blind I/O channel, the fields that ore to be input 
must be selected by the UBSFLD system function. Only those input fields that ore 
currently selected may have values input for them. The UBRFLD system function is 
used to release currently selected fields. The UBXFLD system function selectively 
erases fields. 

Finally, the QBPAGE system function is used to moke changes to the form visible. 
Normally, when a field value is written or an attribute is changed, the changes do 
not appear until o read is issued to the form. The UBPAGE system function is used to 
force changes to appear. The right argument of UBPAGE may be a 1 or 2— item integer 
vector. The first item is the blind I/O stream and the second item is 0 or 1 to 
force changes to the current screen or (if the device is not a screen) 1 to force a 
copy of the form to be displayed on the terminal. If the terminal device is not a 
screen, then changes to the form ore not displayed unless the second item of the 
right argument is 1 or is omitted. 
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Forms Mode 



CE38-04 



Field Definition Matrix 



The form is initially defined using the UBFLD system function. After definition, the 
ottributes and values of the fields can be modified by the QBMFLD system function. 
The left argument for both of these functions must be a field definition matrix. 

This matrix must hove at least four columns and no more than seven columns. The 
first six columns always contain integer values; the seventh column must always 
contain character vectors. Each row of the matrix defines a field. 



Field Definition Matrix Columns 



Field Number. This number is used to refer to the field 
modifying or writing. Field numbers ere integer scalars 
65535. When modifying a field definition, a field number 
modify the definition of all currently selected fields. 



when selecting, erasing, 
in the range 0 through 
value of -1 is used to 



2. Row Number. This number locates the row on the screen in which a field will 
appear. Row numbers are integer scalers in the range 1 through 254. When 
modifying a field definition, a value of -1 must be specified for the row number. 

3. Column Number. This number locates the column on the screen in which a field 
begins. Column numbers are integer scalars in the range 1 through 254. When 
modifying a field definition, a value of -1 must be specified for the column 
number. 

4. Length. This number determines the number of character positions that the field 
takes up. Field lengths are integer scalers in the range 1 through 254. When 
modifying a field definition, o value of -1 must be specified for the field 

I ength . 

5. Field Rendition Attributes. Rendition attributes ore scalar integers whose 
values are the sums of the inclusion values listed in table 16—1. The default 
attributes ore obtained (when defining e field) by using the velue -1 or 0. When 
modifying o field definition, a value of -1 for the rendition attribute is used 
to indicate no change to the current rendition attributes. The value 0 indicates 
the default attributes. 



Table 16-1. Blind I/O Field Rendition Attributes 


Va 1 ue 


Descr i pt i on 


1 


reserved for future use 


2 


reverse video 


4 


fast blink 


8 


s 1 ow blink 


16 


underscore 


32 


decreased intensity 


64 


increased intensity 


128 


hidden 



6. Field Input Attributes. Field input attributes ore scalar integers whose values 
are the sums of the inclusion values listed in table 16—2. The default input 
attributes ore obtained by using the value -1 or 0. When modifying a field 
definition, a value of -1 for the input attribute is used to indicate no change 
to the current input ottributes. 
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Toble 16-2. Bl ind I/O Field Input Attributes 



Value 


Descr i pt ion 


1 


reserved for future use 


2 


constant 


4 


input required 


8 


protected 


16 


letters permitted 


32 


numbers permitted 


64 


graphic characters permitted 


128 


protect and guard field 


256 


all characters permitted 



Attributes that are not supported by the device in use are not available. 

7. Value. Field values are simple character vectors. When modifying a field 

definition, an empty vector is used to indicate that the current field value is 
not to be changed. 



UBFLD Function (Field Definition) 



Syntax: 

M UBFLD I 

Parameters: 

M is a field definition matrix (see below). 

/ is a simple integer scalar representing a valid blind I/O channel. 



Descr ipt ion: 

The UBFLD system function defines the fields indiccted by the left argument field 
definition matrix. The field definition matrix contains definitions of the location 
and size of each field, input attributes, rendition attributes, and the current (or 
initial) value of the field. 



Examples: 

The following example demonstrates the creation of a form for entry of names and 
addresses. Figure 16-1 shows the screen image that results from the form definition 
example. 



FIELDS^Z 7p I I 30 15 0 0 ' AM&l^S. S£fi££K» 2 3 2 5 0 0 •A^^tffi: ' 

FIELDS<-FIELDS,ll]2 3 11 35 0 0 WHQ* 

FIELDS'^FIELDS.ll)'* 4 2 8 0 0 ' AHItRK^S.'- ' 

FIELDS*-FIELDS,[i}5 k II 35 0 0 •SiZS5£^ D&JVl,' 

FlELDS<-FIELDS,[l]e 5 11 35 0 0 'CALSARL, ALMERZA' 



a DISPLAY THE FIELD DEFINITION MATRIX 
FIELDS 

1 1 30 15 0 0 AUSRES^ SQREKH 

2 3 2 5 0 0 NAHE- 

3 3 11 35 0 0 JQK VEa 
k H 2 8 0 0 AHU&ES.^: 

5 4 11 35 0 0 SlL^^El DRIYl, 

6 5 11 35 0 0 CAUQiARl, ALM&ZA 

a SET THE BLIND I/O CHANNEL TO BE USED 
)SET m UC05 ,ORG'FORM ,FUN'UPDATE 
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FIELDS UBFLD 1 





Address Screen 


Name: 


Joe Who 


Address: 


Sussex Drive. 




Calgary, Alberta 



Figure 16—1. Forms Mode Screen Display 



Possible Errors: 

A RAUK ERR is reported if: 

o the left argument is not a matrix or vector. 

o the seventh column of the left argument does not contain scalers or vectors. 
A LENGTH ERR is reported if: 

o the right argument contains more than one item. 

o the left argument contains more than 7 or fewer than 4 columns. 

A DOHAIH ERR is reported if: 

o the right argument is not a simple scalar integer in the range 0 through 9 

i nc I us i ve . 

o the first six columns of the left argument are not scalar integers, 
o the seventh column of the left argument is not simple character vectors or 
scalers. 

o the first column of the left argument contains a value (field number) greater 

than 65535 or less than 0. 
o the second column of the left argument contains a value (row number) greater than 

254 or I ess than 0. 

o the third column of the left argument contains a value (column number) greater 

than 254 or less than 0. 
o the fourth column of the left argument contains a value (field length) greater 

than 254 or less than 0. 
o the fifth column of the left argument contains a value (field rendition) greater 

than 1023 or less than -1. 
o the sixth column of the left argument contains a value (input attributes) greater 

than 1023 or less than -1. 

An I/O ERR is reported if: 

o the field definition is not consistent with CP-6 requirements. 
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UBMFLD Function (Modify Field) 



Syntax: 

H UBMFLD I 



Parameters: 

M is a field definition matrix. 

/ is a simple integer scalar representing a valid blind I/O channel. 



Descr ipt ion: 

The left argument is a field definition matrix as described for the UBFLD system 
function. 

Because the field location and length may not be modified, the value specified for 
them must be 0. A value of -1 for either the field rendition attributes or the field 
input attributes is used to indicate no change in this attribute. An empty vector is 
used to indicate no change in the current field value. 



Examples: 

In the following example, fields 3, 5, and 6 of the current form ore selected and 
their attributes ore modified to reverse video and input required: 

3 5 6 QBSFLD 1 a SELECT OUR INPUT FIELDS 



a THE FOLLOWING EXECUTION OF THE UBMFLD SYSTEM 

a FUNCTION WILL CAUSE ALL CURRENTLY SELECTED 

0 FIELDS TO BE MODIFIED TO THE RENDITION ATTRIBUTE 

0 OF REVERSE VIDEO AND THEIR INPUT ATTRIBUTES TO 

0 INPUT REQUIRED. 

"1 "1 "1 "I 2 * UBMFLD 1 



Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a matrix or vector. 

o the seventh column of the left argument does not contain scalars or vectors. 
A LENGTH ERR is reported if: 

o the right argument contains more than one item. 

o the left argument contains more than 7 or fewer than 4 columns. 

A DOMAIN ERR is reported if: 

o the right argument is not a simple scalar integer in the range 0 through 9 
inclusive. 

o the first six columns of the left argument are not scalar integers, 
o the seventh column of the left argument is not simple character vectors or 
scalars. 

o the first column of the left argument contains a value (field number) greater 

than 65535 or less than -1. 
o the second column of the left argument contains a value (row number) other than 

-1 . 

o the third column of the left argument contains a value (column number) other than 



16-16 



UBMFLD 
Function (Modify Field) 



CE38-04 



-1 . 

o the fourth column of the left argument contains a value (field length) other than 
-1 . 

o the fifth column of the left argument contains a value (field rendition) greater 

than 1023 or less than -1. 
o the sixth column of the left argument contains a value (input attributes) greater 

than 1023 or less than -1. 

An I/O ERR is reported if: 

o the field definition is not consistent with CP-6 requirements. 
UBSFLD Function (Select Field) 

Syntax : 

IV UBSFLD I 

Parameters: 

IV is a simple integer vector of field numbers. 

/ is a simple integer scalar representing a valid blind I/O channel. 

Description: 

The QBSFLD function Is used to select fields that are to be affected by subsequent 
field operations. For example, in order to input a field value, it must have been 
selected previous to the read. A field number of -1 is used to select all currently 
defined fields. 

Examp I es : 

In the following example, fields 3. 5, and 6 are selected: 
3 5 6 UBSFLD 1 

Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a vector or scalar. 
A LENGTH ERR is reported if: 

o the right argument contains more than one item. 
A DOHAIH ERR is reported if: 

o the right argument is not a simple integer value representing a valid blind I/O 

channel (0 through 9 inclusive), 
o the left argument is not a simple integer vector of valid field numbers or -1. 

An I/O ERR is reported if: 

o the operation is not consistent with CP— 6 requirements. 
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UBRFLD Function 



(Release Field) 



Syntax : 



IV UBRFLD I 



Parameters: 



IV 



is a simple integer vector of field numbers. 



is o simple integer scalar representing a valid blind I/O channel. 



Descript ion: 

The UBRFLD system function is used to release (or deselect) a previously selected 
screen field. A field number of -1 is used to release all currently selected fields. 

Examp I es : 

In the following example, fields 5 and 6 ore deselected: 
5 6 UBRFLD 1 

Possible Errors: 

A RANK ERR is reported if: 

o the left argument is not a vector or scalar. 
A LENGTH ERR is reported if: 

o the right argument contains more than one item. 
A DOMAIN ERR is reported if: 

o the right argument is not a simple integer value representing a valid blind I/O 

channel (0 through 9 inclusive), 
o the left argument is not a simple integer vector of valid field numbers or —1. 

An I/O ERR is reported if: 

o the operation is not consistent with CP-6 requirements. 



UBXFLD Function (Expunge Field) 



Syntax: 



IVO UBXFLD IV I 
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Parameters: 

IVO is a simple integer vector of field numbers. 

IVl is a simple integer vector of length two, containing a valid blind I/O 
channel number and an erase level code value of 0, 1. 2, or 3. 

Descript ion: 

The UBXFLD system function is used to erase (or expunge) the specified fields. The 
second item of the right argument controls the extent of the erase. A value of 0 
erases input fields. 1 erases input fields and protected fields, 2 erases input 
fields and constant fields, and 3 erases input fields, constant fields and protected 
fields. A field number of -1 is used to erase all currently selected fields. 

ExampI es: 

In the following example, fields 3, 5, and 6 are erased: 
3 5 6 UBXFLD 1 1 

Possible Errors: 

A RAHK ERR is reported if:. 

o the left argument is not a vector or scalar. 
A LENGTH ERR is reported if: 

o the right argument contains more than two items. 
A DOMAIN ERR is reported if: 

o the right argument is not a simple integer value representing a valid blind I/O 
channel (0 through 9 inclusive) followed by a simple integer value in the range 0 
through 3 Inclusive. 

o the left argument is not a simple integer vector of valid field numbers or —1. 
An I/O ERR is reported if: 

o the operation is not consistent with CP-6 requirements. 
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Appendix A 

CP-6 APL Parameters 



This appendix defines the limits that apply to the CP-6 APL implementation and 
references to (or definitions of) the implementation-defined algorithms. This 
information may be useful in comparing CP-6 APL to other implementations and in 
determining whether an existing APL application con be run on CP-6 APL. 



Arithmetic Limits 



Largest positive number: 8. 3798799562 H 123 ISeSflSa 

Largest negative number: "8. 3798799562 H 123 1872£'152 

Largest counting numbers: (2*60) (~2-'ir60) 

Maximum exponent field width: 5 
Integer tolerance volue: Qcr 
Digits in full print precision: 20 



Array Limits 



Maximum rank: 62 

Maximum index: 34359738367 

Maximum number of items: 34359738367 



System Variabies 



The valid volue range for the nomed system variables is: 
Minimum Maximum 



Nome Value Value Domain 

DCT 0 IE~12 (0..ir"12) 

U!0 0 1 Integer 0 or 1 

UliX character vector 

URL 1 34359738367 integers in range 

UPP 1 20 Integers in range 
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Implementation Defined System Variables 



Name 

UPW 

UPS 



Mi nimum 
Value 

32 

"1 
"2*35 



Maximum 
Value 

390 

1 

"1+2*35 



Doma i n 

integers in range 

integer; for first two items 

integer; for last two items 



Defined Functions 



Maximum number of lines: 65535 
Moximum function definition prompt: 9999.999 



APL input and Output 



Direct input prompt: 
Quad input prompt: 
Function definition prompt 
Quote quod output limit: 



(6p' 

[n] 
none 



Hiscel laneous Limits 



Maximum number of shared variables: 
Identifier length limit: 
Account identification: 
Workspace name length limit 
Shared variable general offer 



16 + unlimited IDS/II shares 
79 

8-item character vector 
31 characters 
20p' • 



File System 



Maximum number of simultaneous file ties: 31 

File name length limit: 31 characters 

File account name limit: 8 characters 



Trigonometric and Hyperbolic Algorithms 







CP-6 LIBRARY 


HART*** 


Cosi ne: 




XPE_9DC0S 


3346 


Si ne : 




XPE 9DSIN 


3346 


Tangent : 




XPE_9DTAN 


4286 


Inverse Cosine: 




XPE_9DAC0S 


4904 


Inverse Sine: 




XPE_9DASIN 


4904 


Inverse Tangent: 




XPE_9DATAN 


4904 


Hyperbol ic Cosine: 




XPE_9DC0SH 


1067** 


Hyper bo 1 ic Si ne: 




XPE_9DSINH 


1986 


Hyperbolic Tangent: 




XPE_9DTANH 


1067** 


Inverse Hyperbolic Cosine: 


XPE_9DAC0SH 


2705* 


Inverse Hyperbolic 


Sine: 


XPE^9DASINH 


2705* 


Inverse Hyperbolic 


Tangent : 


XPE_9DATANH 


2705* 



The standard logarithmic formula equivalents ore used 
to evaluate these functions. 
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** The standard exponential formula equivalents are used 
to evaluate these functions. 

*•* Algorithm number from Computer Approximations. Hart, J. F. , et 
Robert C. Krieger Publishing Company, Huntington, N.Y. , 1978. 



Numeric Algorithms 



CP-6 LIBRARY 



HART 



Exponent iai : 
Gamma-f unct ion: 



Modu I o: 

Natural Logarithm: 
Powe r : 



Matrix Divide: 



XPE_9DEXP 1067 
Chebyshev Approximations to the 
Gamma Function by Helmut Werner and 
Robert Collinge. Also Hart 5422 
when overflow would otherwise occur. 
XPE_9DM0D 

XPE_9DL0G 2705 

XPE_9PWRII 

XPE_9PWRDI 

XPE_9PWRDD 2795 

Golub/Businger algorithm with 
Powell/Reid strategies for 
scaling and row interchanging 
except for square matrices 
where Gaussian reduction 
with partial pivoting is used. 



Semi Numeric Algorithms 



Pseudo-random Number Generation 



V R*-ROLL N;X 
[1] ■^iN^Z*25)/BIG 

[21 R^UlOHlf*ROLLEM^2*3l 
[3] *0 

Ik] BIQ: X^R0LLEH^(2ic3 1 ) x IROLLEM^Z 
7 

V R*'ROLLEH 

[1] a«L<-i?<-l ("1+2*31 )|Qi?Lx65539 
7 
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Pseudo-random Number Generation 



Deal Function 



V R^-A DEAL Bil 
[11 R^iO 
12] R^v B ^ I*UI0 
13] B^?OB-iA 

Ik] L:-^(UA)/X 
[51 RII+B[I],0]*-R[1*0,BII]] 
[6] ■*■ 

[7] XiR^A^R 
[8] 



CP-6 Dependent Algorithms 



Input Conversion: 

Output Conversion: 
Current time: 
Trace display: 



Function display: 



XPN_7NS0TOI . 
XPN_7NS0TOD 
XPN_7IT0NSS 
M$TIME * 
fun[n] value 
fun[n] 0 value 
fun[n] •♦n 

V fun 
[1] line 

V 



Next Definition Line; 



99999 .9991CURR+ I NCRLAST 



where CURE is the current line 
number and I NCRLAST is 1 or the 
value associated with the lost 
digit position entered that 
overrode a previously prompted 
I ine number. 



Read Keyboard: 

Plus: 

Minus : 

T imes : 

Divide: 

Time-Stamp 



Pi-Times 



CP-6 M$READ monitor service * 

DPS8 instructions: DFAD, ADQ •* 

DPS8 instructions: DFSB, SBQ ** 

DPS8 instructions: DFMP, MPY 

DPS8 instructions: DFDV, DFDI . DIV 

A seven item integer vector containing 

the current time as: year, month, day, 

hour, minute, second, and millisecond 

as returned by M$TIME. * 

The closest hardware approximation to pi (to 
19 digits) times the argument value. 



See CP-6 Host Monitor Services Reference (CE74, CE75) 
See DPS8 Assembly Instructions (DH03) 
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Array Representation 



Arrays in CP-6 APL occupy a minimum of 16 bytes of workspace, where a byte contains 9 
bits of information. The total size of the array depends upon the rank and the total 
number of items in the array. 

Character arrays are stored one character in each byte of memory providing 512 
possible characters. Numeric arrays are represented in one of four different methods 
depending, upon the value being represented and the method used to generate the 
value. Logical arrays are used to represent arrays containing only the values 0 and 
1 using one bit. with up to 9 values packed in each byte. Integer arrays are used to 
represent the integer values "34359738368 to 3't359738367 using four bytes for each 
value. Index sequences are used to represent the result of the index generator 
function. This representation always occupies 24 bytes of workspace. Finally, 
floating point arrays are used to represent all other numeric values using 8 bytes of 
workspace for each value. 

Nested orroys are used to represent heterogeneous arrays, and arrays with items which 
are themselves APL arrays. Each item of a nested array occupies 4 bytes of workspace 
where each item contains either a simple scalar value or a pointer to another APL 
array. 



Consistent Extensions to the ISO APL Standard 



CP-6 APL provides many extensions over the ISO and ANSI APL standards. Some of the 
extensions ore minor (in that almost all APL implementations provide the same 
extension) while some provide capabilities not generally available in other APL 
implementations. The use of these extensions in CP-6 APL will make a program 
non-conformant with the APL Standard. The following is a summary of the extensions 
that are found in CP-6 APL. 



Nested Arrays 

CP— 6 APL provides a nested array capability where any item of on array may contain 
another APL array (as a scalar item). The introduction of nested arrays has extended 
the domain of all scalar functions to nested arrays, of all structural mixed 
functions to nested arrays, of all operators to nested arrays and the monadic format 
function creates a display form for a nested array. 

In addition to providing nested arrays, CP— 6 APL arrays may also contain items of 
differing types (mixed character and numeric). 



Additional Primitive Functions 



CP— 6 APL provides eight primitive functions which are not present in the APL 
standard. They are: r (equivalence), monadic f (first). 3 (disclose and pick), c 
(enclose), monadic < (type), dyadic k (grade-up), dyadic t (grade-down), i (I-beam), 
and T (T-bar). 
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Additional Primitive Functions 
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Extensions to Primitive Functions 



CP— 6 APL provides many extensions to the existing primitive functions in addition to 
those noted under the nested or ray datatype. Some of these extensions ore common 
extensions to APL made In other implementations. 

The dyadic ^ (and) function has been extended to permit any numeric value as 
arguments (as opposed to only 0 and 1). This extension returns the 
Least-Common-Multiple of the two values. 

The dyadic v (or) function has been extended to permit any numeric value as arguments 
(as opposed to only 0 and 1). This extension returns the Greatest-Common-Divisor of 
the two values. 

The monadic i (grade-up) and monadic t (grade— down) functions have been extended to 
sort character data and to sort arrays of any rank. 

The left argument of the dyadic / (compress) function may contain positive integers 
less than the maximum index limit. This new function is known os replicate because 
it replicates the right argument values the number of times specified by the left 
argument values. 

The dyadic , (join) function does not report a DOMAIN ERR when the types of the left 
and right argument ore different. The nested array extensions permit arrays to 
contain both character and numeric items. If both arguments are empty, the result 
type is the prototype of the right argument. 

The functions which access the system variable UCT (comparison tolerance) will only 
attempt to access the value if the internal CP-6 APL datatype needs to hove UCT 
appi ied. 

The dyadic p (reshape) function does not report a DOMAIN ERR if the right argument is 
empty. Instead, it fills the resulting array with prototype values (if they are 
needed) . 

The monadic 4 (execute) function always returns a value if the execution of the 
statement is successful. If the statement does not provide a result, execute returns 
an empty numeric vector. The line to execute may also contain system commands or 
f unct i on-def i n 1 1 i on-mode commands . 

The monadic + (conjugate) function does not report a DOMAIN ERR if it is provided 
with on argument of type character. It returns the character value unchanged. 

The [ ]<- (indexed assignment) function does not report a DOMAIN ERR when the type of 
the assigned value is not the same as the type of the name being assigned. The 
result is an array containing data of both types (numeric and character). 

If the left argument of the \ (expand), / (compress and replicate) or p (reshape) 
functions is a singleton, it is treated as a scalar. 

If either argument of the dyadic ? (deal) function is a singleton, it is treated as a 
scalar. 

If the right argument of the monadic % function is a singleton, it is treated as a 
scalar. 
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Additional Primitive Operators 



CP-6 APL provides an operator which is not present in the ISO or ANSI APL standards. 
It is the " (each) operator. 



Extensions to Primitive Operators 

In addition to the extensions noted under the section on nested arrays, CP-6 APL 
contains an extension to the \ (scan) operator. A DOMAIN ERR is not reported if the 
type of the result of applying the function differs from the type of the argument. 

All of the operators in CP-6 APL accept any function as an argument, not just a 
scalar function. 



Additional System Functions 

CP-6 APL provides many system functions in addition to those defined in the APL 
standard. These new system functions include: 

□i4r (set/query function attributes) USITEl/AME (system name) 

DCVr (convert datatypes) USM (set/query function sidetrack) 



In addition to these system functions, this manual includes discussions of APL File 
I/O (section 12), APL I-D-S/II Interface (section 13), Packages (section 14), 
Graphics (section 15), and Blind I/O (section 16) which contains documentation for 
more CP-6 APL system functions. 



Extensions to System Functions 

The UDL, UlfL , USTOP and UTRACE system functions treat a singleton right argument as a 
scalar. 

Namelist arguments (identifier-row in the APL standard) to system functions may 
contain more than one name per row (separated by blanks or carriage returns). In 
this case, the result depends upon the number of identifiers found in the argument, 
not the number of rows in the namelist. 

The dyadic USTOP (set function stops) and dyadic UTRACE (set function trace) system 
functions permit stopping and tracing line 0. 

The QfA^ system function permits its right argument to be a vector with carriage 
return characters separating lines. This function may also be used dyadically to 
create a function with specific execution properties. 
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UXL (translate) 



Extensions to Defined Functions 



Dyadic defined functions may be executed monadical ly . 

The result name in the function header may be enclosed in brace brackets to turn off 
"output potential". 



Additional System Variables 

CP-6 APL provides the following system variables (which are not in the APL standard): 
UPW (platen width). UPS (positioning and spacing). 



Extensions to Systenn Vau-iables 

The value assigned to the system variables Q/O (index origin), UPP (print precision) 
and Qcr (comparison tolerance) may be a singleton of any ronlc. 



AdditionaJ System Commands 

CP-6 APL contains many system commands in addition to those defined by the APL 
standard. (See section 8 for complete descriptions of these commands.) 

The additional commands supplied in CP-6 APL ore: )CATCH, )CONTINUE, )DIGITS, 
)EDITOR, )EHD, )ERROR, )G0 , )GROUP )GRP , )GRPS , )IBEX, )LIHK, )HMS , )OBSERVE , )OFF, 
)OPR, )OPRN, )ORIGIN, )PCOPY, )QCOPY , )QLOAD, )QPCOPY , )QUIT, ) REPORT , ) RESET , 
)SALVAGE, )SEAL, )SET , )SIL. )SIV, )STEP , )TERHIHAL, and WIDTH. 

All of the system command names can be abbreviated to the first four characters. 



Extensions to System Commands 

A CP— 6 APL workspace identifier may contain additional characters to those defined in 
the APL standard. The characters are: $, :, _, and -. The workspace identifier may 
be followed by a period, an 8 character account identifier and optionally followed by 
another period and an 8 character password. 

The )COPY command copies groups (see section 8) and more than one name may be 
specified in the copy list. 

The )DROP command with no workspace identifier drops the workspace created by the 
)COlfTINUE command (see section 8). 

The )ERASE command permits more than one name to be specified to be erased. 

The )FHS and )VARS commands permit two names to be specified which are used to 
delimit the start and end of the list of names to display. 

The )LIB command permits an account name to be specified. 

The )SI and )SllfL commends indicate when an execute or quad entry is found in the 
state indicator. These commands also permit the keyword options ON, OFF and CLEAR to 
be specified. 
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Miscellaneous Extensions 



The quote quad output prompt may be formed by ossignment to (9 multiple times. The 
value assigned to □ is permitted to be any APL array. If an APL statement begins 
with the left pointing arrow (assignment arrow), default output that would have been 
generated by the statement is not displayed. 

During □ input, defined functions may be modified or created, and system commands may 
be issued. 

When an identifier exceeds the identifier length limit, an error is not reported. 
Instead, the name is truncated to the limit. 

Vector notation may be used to create nested arrays. 

Vector assignment may be used to assign the values of a vector to a list of 

identifier names. 

Selective assignment may be used to modify items of an array. 
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Appendix B 

CP-6 APL Character Set 



The appendix describes the atomic vector for CP-6 APL. The CP-6 APL atomic vector 
(QAV) is o character vector of length 512. The lost 256 character positions of this 
vector are not assigned any meaning and are not permitted to appear in APL 
express i ons . 

In the following table each of the first 256 elements of UAV are described in terms 
of their position, the ascii characters to enter on non-APL terminals, the APL 
character, the APL characters that form the overstrike and the name of the character. 
Some of these characters are unassigned and do not hove a meaning. 

APL characters which have no corresponding character in ASCII may be entered as 
mnemonics. Mnemonics are introduced by the $ character and are followed by 1, 2 or 3 
characters which are mapped into the internal APL character during input processing. 
When the introducer is not followed by a defined mnemonic, the characters entered are 
passed through the APL input routine. This permits the $ character to be entered in 
normal input. A true dollar sign can be entered where it could be interpreted as a 
mnemonic by doubling it. That is, $$ is always a single dollar sign. 
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Table B-1 . CP-6 APL Character 


Set 




Index 


ASCII 


APL 


Overst ri ke 


Name 


Index 


ASCII 


APL 


Overst r i ke 


Name 


0 


NUL 








64 


0 


a 




al pha 


1 


SOH 








65 


A 


A 






2 


STX 








66 


B 


B 






3 


ETX 








67 


C 


C 






4 


EOT 








68 


D 


D 






5 


ENQ 








69 


E 


E 






6 


ACK 








70 


F 


F 






7 


BEL 








71 


G 


G 






8 


BS 








72 


H 


H 






9 


HT 








73 


I 


I 






10 


LF 








74 


J 


J 






11 


VT 








75 


K 


K 






12 


FF 








76 


L 


L 






13 


CR 








77 


M 


M 






14 


SO 








78 


N 


H 






15 


SI 








79 


0 


0 






16 


OLE 








80 


P 


P 






17 


DC1 








81 


Q 


Q 






18 


DC2 








82 


R 


R 






19 


DC3 








83 


S 


S 






20 


DC4 








84 


T 


T 






21 


NAK 








85 


U 


U 






22 


SYN 








86 


V 


V 






23 


ETB 








87 


w 


W 






24 


CAN 








88 


X 


X 






25 


EM 








89 


Y 


Y 






26 


SUB 








90 


z 


Z 






27 


ESC 








91 


[ 


I 




left bracket 


28 


FS 








92 


\ 


\ 




back slash 


29 


GS 








93 


] 


] 




right bracket 


30 


RS 








94 


Itak 


♦ 




take 


31 


US 








95 


$_ 






underbar 


32 


BL 






b 1 ank 


96 


$ENC 


c 




enclose 


33 


1 


t 




bong 


97 


a 


A 


k 




34 


$" 






d i oe res 1 s 


98 


b 


B. 


B 




35 


$NE 


/ 




not equal 


99 


c 




C 




36 


$ 


$ 




do 1 1 ars 


100 


d 




D 




37 


$R 


P 




rho 


101 


e 


£ 


E 




38 


$CAP 


n 




cap 


102 


f 




F 




39 


* 


f 




quote 


103 


g 




G 




40 


( 


( 




left paren 


104 


h 




H 




41 


) 


) 




right paren 


105 


i 


I 


I 




42 


* 


* 




star 


106 


j 


I 


J 




43 


+ 






pi us 


107 


k 


K 


K 




44 








comma 


108 


1 


L 


L 




45 


$- 


- 




mi nus 


109 


m 


H 


M 




46 




. 




dot 


110 


n 


tL 


tf 




47 


/ 


/ 




slash 


111 


o 


Q. 


0 




48 


e 


0 




zero 


112 


p 


£ 


P 




49 


1 


1 




one 


113 


q 




Q_ 




50 


2 


2 




two 


114 


r 


R 


R 




51 


3 


3 




three 


115 


s 


S. 


S 




52 


4 


i\ 




four 


116 


t 


r 


T 




53 


5 


5 




f ive 


117 


u 


u. 


U 




54 


6 


6 




six 


118 


V 


V 


V 




55 


7 


7 




seven 


119 


w 


w 


W 




56 


8 


8 




eight 


120 


X 


K 


x_ 




57 


9 


9 




nine 


121 


y 


1 


Y 




58 


: 


: 




colon 


122 


z 


I 






59 


9 


1 




semicolon 


123 


\ 


\ 




left brace 


60 


< 


< 




less 


124 


1 




st i le 


61 


as 






equa 1 


125 


I 


\ 




right brace 


62 


> 


> 




greater 


126 








not 


63 


? 






query 


127 


DEL 
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(cont . ) 




Index 


ASCII 


APL 


Overstrike 


Name 


Index 


ASCII 


APL 


Overst r i ke 


Name 


128 










192 


$MIN 


I 




f loor 


129 










193 


$E 


c 




epsi Ion 


130 










194 










131 










195 


$DLT 






del ta 


132 










196 


$1 


I 




i ota 


133 










197 


# 


X 




t imes 


134 










198 


% 


■r 




d i V i de 


135 










199 


$MAX 


r 




ce i 1 i ng 


136 










200 


$DRP 






d rop 


137 










201 










138 










202 


$W 


u 




omega 


139 










203 


$DSC 


0 




d i scl ose 


140 










204 


k 


A 




and 


141 










205 


" 


7 




del 


142 










206 


- 






over bar 


143 










207 


$LE 






less equal 


144 










208 


$GE 






greater equal 


145 










209 


$0R 


V 




or 


146 










210 


$DMD 


0 




d i amond 


147 










211 


$LTK 


V- 




left tack 


148 










212 


$RTK 


-4 




right tack 


149 










213 


$Q 


0 




quod 


150 










214 


$0 


0 




c i rc 1 e 


151 










215 


$G0 






right arrow 


152 










216 




<- 




left arrow 


153 










217 


$DCD 


i 




decode 


154 










218 


$ECD 


T 




encode 


155 










219 


$C0M 




no 


1 amp 


156 










220 


$EQV 


= 


= 


equ i va 1 ent 


157 










221 


$NOV 


t 




i nequ i vo 1 ent 


158 










222 


$FDI 


t 




find index 


159 










223 


$FND 




c 


f ind 


160 










224 










161 


$SC 


0 




jot 


225 










162 


$RD1 


/ 


/- 


slash bar 


226 










163 


$CUP 


u 




cup 


227 










164 


$XP1 


\ 


\- 


backslash bar 


228 










165 


$GD 




VI 


gradedown 


229 










166 


$LOK 




V- 


1 ock 


230 










167 


$XEC 




iO 


execute 


231 










168 


$FMT 


V 


TO 


format 


232 










169 


$QQ 


□ 


•0 


quote— quad 


233 










170 


SLOG 




0* 


1 og 


234 










171 


$RV1 


e 


0- 


rotate first 


235 










172 


$MDV 


g 




matrix divide 


236 










173 


$TBR 


T 


T~ 


t-bar 


237 










174 


$IB 


I 


Tl 


i beam 


238 










175 


$UDL 


A 




delta underbar 


239 










176 


$TPS 




0\ 


t ranspose 


240 










177 


$GU 


k 


^1 


grade up 


241 










178 


$NND 






nand 


242 










179 


$NOR 


V 


V- 


nor 


243 










180 


$REV 


<D 


01 


reverse 


244 










181 


$00 


D 


00 


quad-zero 


245 










182 


$01 


(D 


10 


quad— one 


246 










183 


$02 


□ 


20 


quod-two 


247 










184 


$03 


□ 


30 


quad-three 


248 










185 


$04 


B 


AO 


quod-four 


249 










186 


$05 


Q 


50 


quad-f i ve 


250 










187 


$06 


B 


60 


quod-si X 


251 










188 


$07 


Q 


70 


quad-seven 


252 










1 tjy 


^WO 


a 


80 


quad-eight 


253 










190 


$09 


S 


90 


quad-ni ne 


254 










191 










255 
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Appendix C 
Error Messages 



Table C-1 is an alphabetic listing of possible APL error messages. The first column 
contains the message and the second column contains explanatory details and recovery 
procedures where appropriate. The effects of error detection on APL processing are 
described in more detail in Section 10. 



Table C-1. Error Messages 


Message 




Descr i pt ion 


name NOT 


COPIED 


The item has the some name as a pendent function in the 
active workspace. 


name NOT 


ERASED 


1 lie 1 L vlll IIUIilv III Ull WUIIIIIIUIIU WU9 IIV i vlUOvU vvwUUSC 

it was a pendent function. 


name NOT 


FOUND 


The item named in a )COPY command was not found (the item 
may have been o local variable). 


ABORTED BY BRK OR 


CTRL-Y 






An enqueue request has been aborted by the user (pertains 
to shared f i 1 es) . 


BAD CHAR 




A bad input character was detected. This is usually the 
result of a transmission error or the input of an illegal 
overstrike. In the cose of nonstandard I/O devices, the 
message can also indicate the input of a character which is 

"illegal" for that device. 


BAD COMMAND 








An improper command construct was detected. 


BAD FILE 


REF 


A bad reference to an existing file name was made during a 
)SAVE command. This could occur, for example, if the 
workspace name specified in the )SAVE command referenced 
some existing workspace that was protected by a password. 
The )SAVE command should be respecified using a different 
workspace name. This message will also result on a 
KOHTIHUE command if a passworded CONTINUE workspace 
al ready exi sts. 
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Table C-1 . Error Messages (cont.) 


Message 


Description 


Dr\Utv.c.N WUr<i\orAt»t 


Damaged workspace reported during loading. It may be 
possible to copy specific items from the broken workspace 
with the )SALVAGE command. 




An enqueue request has been made (pertaining to shared 
files) which, if honored, would create a deadlock stopping 
further activity of two or more users. 


DEFN ERR 


This message is output for any sort of error in function 
definition, such as misplaced del symbol (V), improper 
syntax of header editing, or an attempt to edit a pendent 
f unct ion. 


DOMAIN ERR 


The indicated argument is of the wrong type or out of the 
proper range for the specific function or for the other 
argument. Examples are character data input for a numeric 
operation, or numbers input for a logical operation which 
do not reduce to 0 or 1. See the domain tables in Section 
5 for examples of acceptable types of argument data for 
each APL function. 


ENQ FULL 


The CP-6 Enqueue tables ore full. 


FILE ACCESS ERR 


This file I/O error often means a password is missing or is 
incorrect . 


FILE DAMAGE 


This file I/O error indicates some damage to the file 
contents was discovered, but not necessarily to every 
record or component in the file. Recovery is often 
possible by copying undamaged material to a new file, 
replocing damaged items. 


FILE IN USE 


The file named in a )SAyE command is currently in use. 
i.e., another user may be simultaneously executing a load 
of that file. Since this situation is a momentary timing 
conflict, the user should retry the command after a short 
wait. This type of timing conflict may also occur when 
using file I/O. 
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Table C-1 . Error Messages (cont.) 


Message 


Descr i pt i on 


FILE 


INDEX ERR 


This file I/O error may mean that an index (record 
identifier, sometimes called a key) is incorrect, or on 
attempt has been made to read beyond the limits of a file. 


FILE I/O ERR nnn-xxxxx- 


s 






This is a general file I/O error message. It indicates 
errors detected by the monitor and corresponds to I/O error 
codes shown in the CP— 6 Programmer Reference Manual (CE40). 


FILE 


NAME ERR 


This file I/O error may mean that a file identifier is 
improperly formatted, an attempt has been made to use a 
file that does not exist, or an attempt has been made to 
create a file that already exists. 


FILE 


SPACE TOO LOW 


Either the user's or the packset's file space limit has 
been reached. This can occur when workspaces are being 
saved or during file I/O operations. Recovery is usually 
possible: the user drops unneeded files from his account 
and retries the aborted statement. 


FILE 


TBL FULL 


This file I/O error means that the maximum permissible 
number of files have been "tied" (designated). 


FILE 


TIE ERR 


This file I/O error may mean either that the file has not 
yet been opened (designated as an input or output stream), 
or that the file being opened has already been opened, or 
that an attempt has been made to write into a file owned by 

another user. 


FORMAT SYNTAX ERR 








A syntax error was detected in the left argument of a UFHT 
expression. See Section 9 for an explanation of correct 
syntax. 


I/O ERR 








This message indicates that an irrecoverable system I/O 
error occurred and an error exit has been made from APL. A 
system I/O error should be reported to the user's field 
representative along with the conditions under which it 
occurred (see also SYS ERR). 
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Table C-1 . Error Messages (cont.) 


Message 


Descript ion 


I/O ERR nnn-xxxxx-s 


If blind I/O was being used, this message indicates that 
the requested blind read or write could not be executed for 
some reason. The user may retry the I/O or otherwise 
continue operation. 

The error codes are described in the CP— 6 Programmer 
Reference Manual (CE40) . 


INDEX ERR 


The index subscript specified in an expression is out of 
the range of the particular array to which it is applied. 
For example, if A is a four-item vector, the expression 
A16] would generate on INDEX ERR since the requested sixth 
item does not exist. 


LENGTH ERR 


The length(s) of the indicated argument(s) ore not 
conformable or are incorrect for the function used. For 
example, the expression 9 7 8+53 results in a LENGTH ERR 
because the two vectors do not have the same number of 
i terns. 


LINESCAN ERR 


An obvious error in form (leading right bracket, misplaced 
colon line ending with a function, etc.) was detected in 
the scon of a line input for execution or function 
definition. No port of the line is executed. In function 
definition mode, the line is entered as part of the 
function and may then be replaced or edited. 


NO RESULT 


A defined function that generated no result was used in a 
context that requires a result. 


NO SHARES 


Another user logged onto the same account is using shared 
variables. Create a unique account identifier with the 
USVH system function. If the shared variable administrator 
is not available or has become unavailable, this message is 
reported and the APL user may no longer access the 
variables he may have previously shared. 


NOT APL FILE 


This file I/O error means that a component read failed 
because it did not hove the structure required by APL. 
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Table C— 1 . Error Messages (cont.) 



Messoge Descript ion 



NOT GROUPED 

The group name specified in a )GROUP or )GRP command 
references an existing item which is not a group. A 
different group name must be used. 



NOT HELD 

The QFDEQ system function specified a file and resource 
that is not currently enqueued. 



NOT SAVED, THIS WS IS name 

If "name" = CLEAR WS, either there is nothing to save or 
the )SAVE command did not specify a name for the saved 
workspace. Otherwise, the )SAVE command named an existing 
saved workspace and the active workspace name is different. 
Change the active workspace name or drop the saved 
workspace. 



OPEN QUOTE 

The Execute function has been used on on argument that has 
an odd number of quotes before the end of the line (or 
first embedded carriage return). 



RANK ERR 

The rank of the indicated argument is incompatible with the 
function or with that of the other argument. 



SEALED WS 

An attempt was made to save a sealed workspace. 



SI DAMAGE 

A suspended function has been erased or replaced, and the 
state indicator has been modified to delete all references 
to it from its active list. This may occur in function 
definition, or upon execution of an )ERASE or )COPY 
command. 



SI DAMAGE WILL RESULT: PROCEED? 

This warning message is output in function definition when 
the header of on existing active function is changed. It 
indicates that references to this function in the state 
indicator list will be damaged if the header change is 
implemented. In order to avoid SI damage, the user may 
restore the header to the old form or chonge the function 
name in the header before closing the function. The user 
types YES in reply to the warning message. 
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Table C-1 . Error Messages (cent.) 



Message Descript ion 



SING. MATRIX 

The right argument of a matrix divide operation (@) is a 
singular matrix, i.e., it had no inverse. 



SV QUOTA EXHAUSTED 

The APL user may share up to 16 variables at any one time. 
This message is reported if the user attempts to share 
another variable. 



SYNTAX ERR 

Improper syntax was detected in the executed line. 
Examples of improper syntax are unbalanced parenthesis or 
an attempt to assign a value to a label. 



SYSTEM ERR 

An irrecoverable system error of indeterminate origin has 
occurred and an error exit has been made from APL. If APL 
is reaccessed, it should operate correctly unless the 
conditions which led to the SYSTEM ERR recur. Please 
report these problems to Honeywell. 



TOO BIG 

A )COPY command refers to more material than would fit in 
the current workspace; no items were copied. 



TOO BIG TO LOAD 

The workspace specified in a )LOAD command was saved by a 
user with larger memory allocation than the present user, 
and there is insufficient space for the workspace to be 
loaded (in some cases it cannot even be copied). See also 
the description of the )COPY command, Section 8. 



TRUNCATED INPUT 

The input line was too long. 



UNDEFINED 

The indicated symbol has not been assigned a value. 



WS FULL 

The active workspace is full. This may occur during 
execution, in function definition, or because of a )GROUP 
command. Depending on the particular situation, the user 
may choose to use an )ERASE command to erase unneeded 
objects from the workspace, clear the state indicator, or 
)CLEAR the entire workspace in order to free up space. 
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Table C-1 . Error Messages (cent.) 


Message 


Descript ion 


WS NOT FOUND 


The workspace file specified in a )LOAD or a )COPY command 
was not found. 
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Appendix D 

CP-V Compatible Workspace Functions 



CP-6 APL provides a set of intrinsic functions, LCR, tWH, end LTE to aid in 
conversion from CP-V to CP-6. This appendix is provided for CP-V conversion purposes 
only. CP— 6 APL provides more powerful system functions to perform these taslcs. 

Canonical Representation 

The LCR intrinsic function converts user functions to character form, creates 
user— defined functions, and locks existing functions. 

Function to Text 
R*-l AC/2 A 

If A is not a character vector representing a valid name in APL, DOMAIN ERR is 
reported. 

If A contains c name which does not represent a user-defined function in the dynamic 
environment, DEFN ERR is reported. 

If no error is indicated, /Z is a character vector consisting of lines of the defined 
function with embedded carriage returns as separators. 

Text to Function 
R*-2 LCR LL 

li LL is not a line list, DOMAIN ERR results. 

DEFN ERR is reported if the 'header' line is not in the proper format for a function 
or if the function name has an active referent which is not a user function. 

If no errors occur, a defined function, with the name specified by LL, is creoted. 

R \3 a character vector indicating the name of the function created. 

Locking Function 
R-^d dCR NL 

NL must be a namelist. For each name in NL, if the current referent is o function, 
it is locked. If not. the name is included \n R. 

A is a character vector consisting of any names in NL which were not current function 
names . 
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Intrinsic To Text 



R \s a character vector containing the name of the intrinsic mentioned in A, an 
assignment arrow, and the particular intrinsic definition statement that defined the 
named intrinsic. 



Worl<space Management 

The workspace management function, tWH, is a dyadic intrinsic function providing a 
variety of operations described below. 

Expunge, Local (Active) 



IfL must be a name list. The active referents of names found in NL are erased. is a 
namelist of any names for which referents were found but not erased. 



Expunge, Global 
R<-Z LWN HL 

Same as 1 LWH NL except that only global referents of names are erased. 



List Workspace Named Items 
R^3 LWM I 

The value of / must be on integer from 1 to 6. R is a character vector with carriage 
returns separating the names. The entities named depend on /. 



I 


Category Listed 


1 


Labels. 




2 


Act i ve 


variables 


3 


Act i ve 


f unct ions 


4 


Groups. 




5 


Global 


variables 


6 


Global 


f unct ions 



List Elements of a Group 



A must be a character vector containing one name. is o character vector with names 
of the members of group A. 

List Workspace Parameters 
R<-5 IMM I 

The value of / must be on integer from 1 to 8. R depends on the value of /. 



R*-l IMM NL 



R^-ii LWM A 



I 



R 



1 
2 
3 
4 
5 
7 
8 



WSID as character vector. 

State indicator as character vector with embedded line feeds. 



Origin as integer. 
Width as integer. 
Digits as integer. 
Symbol table size. 



Number of symbols still available. 
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Identify Local Use of Names 
R*-6 LWH NL 

The namelist NL Is scanned for current use of the names. R \s a numeric vector. 
Values are as indicated. 



0 


No current referent. 






1 


Logical variable. 






2 


Character variable. 






3 


Integer variable. 






4 


Real variable. 






5 


Index sequence. 






7 


Label . 






8 


User-defined function. 


n i 1 ad i c , 


, no result. 


9 


User-defined function. 


n i 1 ad i c , 


, with resu 1 t 


ie 


User— defined function. 


monad i c , 


, no result. 


11 


User-defined function. 


monadi c , 


, with resu 1 t 


12 


User— defined function. 


dyad i c , 


no result. 


13 


User— defined function. 


dyad i c , 


with result. 


14 


Intrinsic function, dyadic. 




15 


Intrinsic function, monadic. 




16 


Intrinsic function, ni 


1 ad i c . 




17 


Group. 







Identify Global Use of Names 
R*-l l^WM NL 

Simi lor to 6 tWM except that global use of names is indicated. 

List Storage Requirements for Named Active Items 
R<-B LVM NL 



NL is a namelist. R \s a numeric vector. Each item of /Z is the number of bytes of 
workspace occupied by the active referent. 

List Storage Requirements for Named Global Items 
^•^9 LVM NL 

NL is a namelist. R is a numeric vector. Each item of R is the number of bytes of 
workspace occupied by the global referent of the corresponding name. 



Text Editing 

The character editing function, LTE , provides five capabilities, described below, to 
facilitate the examination and modification of character variables in APL. 

Text Index function 
/?<-! LTE L 

L is a 'list' with two items. 
L^l LTE (TVtDV) 

TV moy be any character vector. 

DV is a character scalar or vector of 'delimiters'. 



R is an N-by-2 numeric matrix. Each row contains the index and length of a string of 
non-delimiter characters in 71^. The values of column 1 of R ore D/O dependent. 
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Substring Search 
R^Z LTE L 

L must be a list with 2, 3, or 4 items. 
RfZ LTE (TYiSS) 

TV may be any character vector. 

5^5 may be any character scalar or vector not longer than TV. 
LTE (TV;SS;FCOL) 

FCOL may be any integer scaler value such that FCOL is less than or equal to the 
highest index value of TV. FCOL indicates the first column in TV at which search is 
to start or 

L<-2 LTE (.TViSS-.FCOL-.LCOL) 

LCOL may be any integer scalar value less than or equal to the highest index value of 
TV and greater than or equal to FCOL. LCOL is the last column of TV involved in the 
search. 

R IS a numeric vector with the beginning indexes of non-overlapping occurrences of SS 
in TV, starting at position FCOL and ending at LCOL. 

Substring Search and Replacement 
R^Z LTE L 

L must be a list of 3. 4, or 5 items. 

LTE {.TViSSiRS) 
TV may be a character scalar or vector. 

S5 may be a character scalar or vector not longer than TV. 
RS may be any character scalar or vector. 

R IS a character vector formed by replaced occurrences of SS, in TV, by RS. 
Replacement i s on a non-overlap basis. Or 

L*3 LTE (.TV;SS;RSiFCOL) 

FCOL may be any integer scalar value such that FCOL is less than or equal to the 
highest index value of TV. FCOL may also be null. 

LTE iTViSS'.RSi FCOL; LCOL) 

LCOL may be any integer scalar value less than or equal to the highest value of TV 
and greater than or equal to FCOL. 

Substring Replacement (Without Search) 
R^k LTE L 

L is a list with 4 items. 

LTE {TV tRS ; FCOL i LCOL) 

TV must be a non-empty character vector. 

RS must be a character vector or scalar. It may be empty. 

FCOL must be an integer scalar representing a valid index of TV. 

LCOL must be an integer scalar representing a valid index of TV. LCOL must be 
greater than or equal to FCOL. 
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R is formed by replacing that portion of TV bounded by FCOL and LCOL by the string 
RS. If RS is empty, this constitutes deletion of a specified subset of TV. 



String Comparison 
R^5 LTE L 

L must be a list with two items: 
i<-5 LTE {A',B) 

A and B must be character vectors or character scalars. 

R \9 Q two-item numeric vector describing the comparison of A and B. Comparison is 
based on the ASCII collating sequence as modified to support the CP-6 APL character 
set . 

The first item of R indicates which item of L should be first in left to right sorted 
order . 



0 means the chorocter vectors are identical. 1 means / should sort first. 2 
means B should sort first. 

The second item of R indicates the lowest position I at which Ail) and Bil] differ. 

If A and B are identical, the second item of R is —1. Thus /? is 0 "1. 

If B is longer than A but AlH - BlI] that is B differs from A only by being longer, 
then A is considered first in sorting order and ^ is 1 ~1. 

If A is longer than B, but each BID « All] then R is 2 -^. 



T-bar Functions 

The T— bar function, t (the encode character, t, overstruck by the negative sign, ~) 
is provided for certain system interfaces. 

One use of T— bar is the character generator function. It converts integer data into 
corresponding character data, and thus allows the user to generate special 
characters, possibly unrecognized by APL. The integer n corresponds to the nth 
character in the table of APL Codes. This is equivalent to indexing QAV. 

To generate the nth character, the following form is used. 

The left argument must be the scalar integer 2; this designates that the T— bar 
function is to be used for character generation. The right argument may hove any 
shape, but its domain must be integer, with values between 0 and 511. The result has 
a shape identical to the right argument, but is character data. 



File Input/Output 

CP-6 APL provides more functionality than is available with these functions through 
the system functions discussed in section 12. The file intrinsic is: 

A fname B 

where 

A the I/O operation number (ranging from 1 to 29). 
B is the argument applicable to the I/O operation. 
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Opening and Creating Files 

Following are the forms for the set of functions required to establish parameters 
prior to opening a stream to a file. 

o Establishing "file number": 

1 fname B 

where B is a positive integer specifying the file number to be used for subsequent 
file operat ions. 

o Establishing file name: 

2 fname B 

where B is a character vector specifying the file name for the currently set file 
number . 

o Establishing or resetting account: 
2 fname B 

where B is either zero or a character vector specifying the account for the currently 
set file number. 

o Establishing or resetting password: 

4 fname B 

where B is either zero or a character vector specifying the password for the 
currently set file number. 

o Establishing file identification as a single primitive: 
21 fname fid 

where fid is a character vector specifying a CP-6 file identifier in the some format 
permitted for system commands such as )LOAD. 

o Assigning serial numbers for pack set utilization: 

20 fname B 

where £ is a character vector of up to 6 characters, or the numeric value 0. 
o Opening stream in indicated mode: 

5 fname B 

If B is on integer specifying the mode of DCB for the currently set file number, as 
f ol I ows: 

1 indicates FUN=IN.DISP=NAMED.EXIST=OLDFILE. 

2 indicates FUN=CREATE.DISP=NAMED. EXIST=NEWFILE. 
4 indicates FUN=UPDATE.DISP=NAMED. EXIST=OLDFILE. 

8 indicates FUN=CREATE.DISP=SCRATCH.EXIST=NEWFILE. 
17 indicates FUN=CREATE.DISP=NAMED. EXIST=ERROR.TEST=YES. 
20 indicates FUN=UPDATE,DISP=NAMED. EXIST=OLDFILE,SHARE=ALL. 
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C I OS i ng Files 

o Closing and saving the file for indicated file numbers: 

6 fname B 

where B is an integer specifying the file number. 

o Closing and releasing the file for indicated file number: 

7 fname B 

where the argument B is the same as above. (This form is used to delete files.) 
Maintaining Key Range and Current Key Value 

When files are created by APL or accessed in other than sequential mode, primitives 
are provided to find the key range of an existing file. When a file is opened in 
CREATE mode, values for the 'first component' and 'last component' are initialized to 
empty vectors and updated when the first record is written. 

o Return the value of a designated key for the currently set file number: 

8 fname B 

where B is 1, 2, or 3, specifying which key the value is to be returned for (the key 
returned will be that for the currently open file, if any. of the most recently 
referenced file number): 

1 indicates that the value of the first key in the file. 

2 indicates that the value of the current key is to be returned. 

3 indicates that the value of the highest key is to be returned. 

o Setting the value of the current key for the currently set file number: 

9 fname B 

where B is on integer or character vector specifying the value for the current key. 
Wr i t i ng APL Records 

o Writing a record containing the value of an expression: 

10 fname expression 

The currently set key value and file number are used, 
o Writing a component: 

11 fname expression 

The record contains the time, dote, and the user's account and name, and the 
expression value. The currently set key value and file number are used. 

Writing Non-APL Records 

Data records may be written that do not retain the APL internal attributes of 'shape' 
and other internal reference dote. 

22 fname B 

where B is any APL expression. The date represented by B is written as a single 
record in ravel order. If £ is o logical vector the length is rounded up to a 
mul tiple of 9 bits. 
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Reading APL Records 

o Reading a data record: 

12 fname B 

where B is on integer specifying the size of the data record in bytes. The data 
record is read using current key and file number. 

o Reading a component databtock: 

13 fname B 

where B is an integer specifying the key value, 
o Reading a component user/time stamp: 

14 fname B 

where B is an integer specifying the key value. The identification record is 
returned as a character vector with the following format: 



DATE bb TIME ACCT UNAME 

1 6 7 8 9 16 17 24 25 36 

Reading Non-APL Records 
23 fname B 

Reads a non-APL record using currently set key and file number. B is an integer 
specifying the record size in bytes. The result is a character vector. 

Deleting Records Or Components 
o Deleting a specified record: 

15 fname B 

16 fname B 



where B is an integer specifying the key value. The current file number is used in 
deleting the record. 

Sequential Access to Existing APL Files 
17 fname B 



where B is on integer specifying the size of the record in bytes. Records are read 
sequentially, using the current file number. If an integer of zero is specified, the 
record is accessed but data is not read, regardless of actual record size. 

13 fname 0 



This is similar to "13 fname B" except that 
component record, records are skipped until 
read, the current key is set to that of the 
is found, an error is reported. 

14 fname 0 



it reads the next record. If it is not a 
0 component record is reached. At end of 
last record read. If no component record 



This is similar to "14 fname 5" except that it skips forward to next component 
record. The current key is updated. If no component record is found, an error is 
reported. 
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Sequential Access to Non-APL Files 

24 fname B 

where B is an integer specifying the size of the record in bytes. Records are read 
sequentially, using the current file number. Operation is analogous to 23 fname B 
except that the read is sequential rather than keyed. 

Converting Data Types 

Primitives 23 and 24, for reading non-APL records, create character vector results, 
o Convert charocter vector to logical vector. 

25 fname B 

where S is a character vector. The result is a logic vector consisting of the actual 
data in B. 

o Convert character vector to integer vector. 

26 fname B 

where £ is a character vector. The length must be a multiple of 4. The result is an 
integer vector consisting of the actual data in B. 

o Convert character vector to real vector. 

27 fname B 

where S is a character vector. The length must be a multiple of 8. The result is a 
numeric vector consisting of the actual data in B. 

Controlling Access to Shared Files 

The following features are provided to permit the user to lock out records of a file 
for purposes of reading without other intervening updates or completing an update 
without interference. 

o Locking out a record. 

28 fname B 

B Is a key value. Causes the designated record to be enqueued for exclusive use. 
o Releasing a locked record. 

29 fname B 

B IS a key value. 

Listing File Names and Numbers 

These operations may be used in functions designed to list file components by number, 
with or without contents of the records. 

o File names in a specified account 

18 fname B 

where B is a character vector specifying a user account. Result is a character 
matrix. Each row has account in columns 1 through 8 and file name in columns 10 
through 40. 

o Names or numbers of currently open files 

19 fname B 
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where B is on integer specifying the structure of the result as follows: 

1. indicates a character matrix with names of currently open files, one file per 
row. 

2. indicates a numeric vector with the currently open file numbers. 
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Appendix E 

Honeywell CP-6 APL Summary 



Scalar Primitive Functions 



All scalar functions are applied i tem-by-i tern on all operands at all levels of 
nesting. A scalar or single item array may be used as an argument of a scalar dyadic 
function end its value is applied to all items of the other argument. 



Table E-1. Scalar Monadic Functions 



Form 


Descr i pt i on 


+Y 


Conjugate of Y (Y) 


-Y 


Negate Y iO-Y) 


xY 


Sign of Y ("1, 0. 1) 




Reciprocal of Y (l^Y) 


*Y 


e to the J"th power 


n 


Ceiling of Y (round up^ 


lY 


Floor of Y (round down; 


\Y 


Absolute value of Y 


9Y 


Natural logarithm of Y 


lY 


Factorial of Y (Gamma of Y+l) 


OY 


Pi times Y 





Table E 


-2. Scalar Dyadic Functions 


Fo rm 


Description 


X+Y 


Add Y to X 




X-Y 


Subtract Y from X 




X*Y 


Multiply r by X 




X^Y 


Divide Y into X 




X*Y 


X raised to the power Y 


X\Y 


Maximum of X and Y 




XIY 


Minimum of X and Y 




X\Y 


X residue of Y (rema 


inder of Y^X) 


Xf^Y 


Least common multiple of X and Y (and) 


XvY 


Greatest common divisor of X and Y (or) 


X\Y 


Binomial coefficient 


. Number of combinations of Y 




things taken AT at a 


t ime 


X9Y 


Base X log of Y 




XOY 


Ci rcular functions: 
oor (l-r*2)*0.5 






lOr sine r 


~10Y arcsin Y 




20Y cosine Y 


~20Y arccos Y 




30r tangent Y 


"30r Cretan Y 




kOY {l+ri-2)*0.5 


"*0r rx(l-}'*~2)*0.5 




SOY sinh r 


~50r orcsinh Y 




60r cosh Y 


"eor orccosh Y 




70Y tanh Y 


~10Y arctanh Y 
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The relational and logical functions obey the rules of scalar conf ormabi I i ty and 
return 0 if the condition is false, and 1 if true. 



Table E-3. Relational and Logical Functions 


Form 


Description 


K<Y 


X less than Y 




X less than or equal to Y 


X>Y 


X greater than Y 


X^Y 


X greater than or equal to Y 


X=Y 


X equal to Y 


X*Y 


X not equa 1 to K 




The following functions operate on arguments which ore 




0 or I. 


Xi^Y 


X end Y (1 if both X and Y are 1) 


X^Y 


X or Y i^ if either A: or K is 1). 


X*'Y 


X nand Y (not both X and Y) 


XyY 


X nor Y (neither X nor Y) 


-Y 


not Y 



E-2 



Scalar Primitive Functions 



CE38-04 



Mixed Functions 



Table E-4. Mixed Functions 


Foriti 


Desc r i pt i on 


KpY 


Reshape Y to ditnensions X. 


oY 


Shaoe of Y 


XiY 


Index of first occurrence of Y within X, 


lY 


First Y consecutive intfiaers from index oriain 

1 119^ 1 \#WII9VWUklTC IllkwUCIW Will IIIU9A VI IUIIIb 


Xt Y 


1 if X occurs in Y, otherwise 0. 


tY 


Type of Y. 


Xz.Y 


1 if X and Y are identical otherwise 0 

1 11 n wiiu 1 uiw iwvii^iwwif Wfciiwivfiow w* 


=Y 


Moximufn nest i no denth of Y 

inu A iiiiuiii IIV9WIIIU uwi/wii wi 1 • 


XTY 


Representation of Y in number systetn X. 


XiY 


Value of Y in number system X. 


X?Y 


X infenpr^ ^^lec^teH ronHom Iv without renetition 

A IllkvU^IO ^^IVWWVU lUIIU VI Illy VTI LIIVUW lv|^v^i WIVil 




f rom (dea 1 ) • 


?Y 


A r Q n d orn intcQcr fr oiTi Y 


X<i>Y 


Y rototcd 0 1 onQ last dimension by X, 


XQY 


Y rotn^AH nlonn fir^f HiirtAnoiAn Kw JK 
i iwLULwU uiviiy 1 1 low uiMidioiuii uy a • 


X^IH]Y 


Y rototod olonQ t h€ ^ ' t h d i mens i on by AT. 






QY 


Y rfiVArsfid fliona first Hi rriAn^ ion 


^[N]Y 


Y revArsAd alonn fhA V*th Hi mAn^ i nn 




TransDOfse of Y hv coorHinntA^ in X 




T rnnsno^A of Y i hv rAVAr^ino nl 1 coorHi not a^^ 


X .Y 


X i o i haH to Y n 1 onn thA In^t i^oorHinotft 


X, lt/]Y 


If H is an integer, X is joined to Y 




0 1 onQ the Af'th coordinate of Xi otherwise, 




X and Y ore joined (laminated) along the new 




coordinote. 


. Y 


Rove 1 of Y (nalc^ Y ci vector^ ' 


X^Y 


Take the first X items from Y iX>0) or 




take the last {\X) items from Y {X<0) . 


♦ K 


ni^flo^A thA fir^t it Am f rom Y 

L^lwWirl\^9w kllC II 19V IVwIII II Will I « 


X^Y 


Drop the first X Items from Y iX'>0) or 




drop the lost (\X) items from Y {X<0) , 


XiY 


The indices of Y select it ems (^or rows ) of 




Y in increasing order of magnitude usin9 the 


iY 


^ol Int inn ^AOiiAn^A Y 

lULIIIU OCUU^II^C /V* 


The indices of Y select items of Y in 




incrpn^inn otHat of innoni tiiHp 

Ill^rl^UOIIIU vlUCi \J \ IIIUmIII lljuc* 


XfY 


The indices of Y select it ems (or rows ) of 




Y inHAcrAO*{ino otHat of mnonttiiHA imino thA 

i III UwVI CUwIliU UIUCI Wl IllUUIIt LUUw UwlHU Lllw 


n 


col lot i no <iPOiiAncA JK 
\^ w i luciiiu acw^uwii^w A* 


The indices of Y which select items of Y 




in decreasing order of magnitude. 


cY 


Enclose of array Y (make a nested scalar). 


c[N]Y 


Enclose along selected axes of Y. 


:>Y 


Disclose Y, by decreasing depth and increasing rank. 


o[N]Y 


Disclose Y, inserting new axes at N. 


X:>Y 


Select item from array Y at depth (pX). 


BY 


Inverse of matrix Y. 


XBY 


Matrix division (least squares fit). 


X^Y 


Format Y according to specifications in X. 


»r 


Format of Y. 


iY 


Evaluate APL expression contained in Y. 
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Primitive Operators 



In the following examples, f and g stand for any dyadic function and h stands for a 
monadic function. 



Table E-5. Operators 


Form 


Descript ion 


f/r 


reduction olong the lost dimension of Y 




reduction along the N'ih dimension of Y 


f /y 




f\r 


scan along the last dimension of Y 


f\[N)Y 


scan along the A^'th dimension of y 


f\Y 


scan along the first dimension of Y 


X/Y 


replication along the lost dimension of Y 


X/[N]Y 


replication along the A^'th dimension of Y 


X/Y 


replication along the first dimension of Y 


X\Y 


expansion along the lost dimension of Y 


X\IH]Y 


expansion along the ^^'th dimension of Y 


X\Y 


expansion olong the first dimension of Y 


X f.g Y 


inner product of X and Y 


X o.g Y 


outer product of X and Y 


X 1" Y 


apply function f to each item of X and Y 


h" Y 


apply function h to each item of Y 



System Variables 



Table E-6. System Variables 


Nome 


Descr i pt i on 


UAV 


Atomic vector. The full CP-6 APL character set. 


DCT 


Comparison tolerance. Used in numeric comparisons. 


Uio 


Index origin. Used in indexing, t, i. 


ULC 


Line counter. Vector of lines in execution. 


ULX 


Latent expression. Executed after )LOAD. 


DPP 


Print precision. Maximum digits in numeric output. 


UPS 


Positioning spacing. Control nested array display. 


UPV 


Print width. Maximum width of output lines. 


DHL 


Random link. Seed for random number generator. 


USA 


Stop action. Control entry into direct input mode. 


DSP 


Session parameter. Variable saved across )LOAD's. 


UTS 


Time stamp. Year, month, day, hour, min. sec, mi 1 1 isec. 


UTT 


Terminal type. 


WL 


User load. Number of users logged onto system. 




Workspace available. Measured in bytes. 
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Table E-7. Special Symbols 


Form 


Descr i pt i on 


( ) 


Parentheses. Expressions may be of any complexity 




and are evaluated from right to left except as 




indicated by parentheses. 


A[X] 


Indexing. Returns an array of shape (.pX) . 




Indexed assignment. The elements of A selected 




by the indices X ore replaced by Y. 


(A f B)<-Y 


Selective assignment. The elements of B 




selected by the expression (A f B) are replaced by 




Y. The function f may be one of the following 




dyadic functions: Q, <D, 6, p, /, or o. 




The function f may also be one of the following 




monadic functions: 0, 0 or , (ravel). 


{A B)*-Y 


Vector assignment. A is assigned the 




first value in the vector Y and B is assigned the 




second . 




Branch. If X is on empty vector, execution 




continues. If the first item of / is 0 




or beyond the range of statement numbers, 




execution of the function terminates. 




Terminates execution of function and related 




pendent functions. 


Quad output. Prints the value of X. 


^x 


Bore output. Prints X without terminating 




carriage return. 




Quad input. The input expression is evaluated 




and assigned to X. 


'XYZ' 


Character vector of- 3 elements: XYZ. 


0 


Lamp. Characters to the right of this symbol 




are treated as commentary. 


7 


Del. Enter or exit function definition mode 


9 


Lock function. 


X: 


Label. AT i s a line label within a function. 


i 


Semicolon. Index separator. 


0 


Diamond. Statement separator. 
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Function Definition 



A 7 preceding the name of a defined function is used to enter definition mode. In 
definition mode, entries are held and saved in a function body for later execution. 
Each entry in definition mode is preceded by o prompt containing a line number in 
brackets. 





Table E-8. 


Function Header Syntax 


Va 1 ence 


No Resu 1 t 


Exp licit Resu 1 1 


Ni Iodic 


V fname 


Vr* fname 


Monadic 


V fname b 


Vr<- fname b 


Dyadic 


Va fname b 


Vr+'O fname b 



Table E-9. Directive Summary 


Ent ry 


Descript ion 


[0] 
tnDl 
[n-mD] 
tnDp] 

[n-tn;/st/] 

[n-m;/st/S/rt/I 

[An] 

[An m] 

[An-m] 

tAn-m:/st/l 

I /SI/] 

l\SI\] 


Display the entire function. 
Display 1 ine n. 

Display lines n through line m. 
Ed i t 1 i ne n . 

Display lines containing 'st' in lines n-m. 
Change string 'st' to 'rt' in lines n-m. 
De 1 ete 1 i ne n . 
Delete 1 i nes n and m. 
Delete lines n through line m. 
Delete lines n-m which contain 'st*. 
Find next occurrence of string '51'- 
Find previous occurrence of string 'SI'- 



Defined Function Controls 



Table E-10. Defined Function Controls 


Name 


Description 


R'*-! UAT F 

W+ UCR F 
UFX H 
N<-A UFX H 

E-^ USH F 
E*-E USH F 
Vf- USTOP F 
V<-V USTOP F 
Vt- UTRACE F 
V<-V UTRACE F 


Return function attributes (1=valence, 

2=create t ime ,3=p roper t ies,4=c rector) . 

Return function's canonical representation. 

Fix canonical representation, return name. 

Like UFX but also set execution attributes. 

i4 is a 4-item logical vector controlling 

attributes: disployable, suspendable, 

i nter ruptab 1 e , errorable. 

Return function's sidetrack matrix. 

Set function's sidetrack matrix. 

Return function's stop vector. 

Set function's stop vector. 

Return function's trace vector. 

Set function's trace vector. 
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Sidetracking on Errors and Interrupts 



The USH system function is used to set and obtain the current sidetrack settings for 
a defined function. The optional left argument is a sidetrack matrix of shape iH,2) 
where each row contains a line number in the first column to indicate where execution 
will resume when the error number in the second column occurs. The right argument is 
a namelist containing the name of the defined function whose sidetrack matrix is to 
be set. If the optional left argument is not present, the result is the sidetrack 
matrix of the function named. 





Tab 1 e 


E— 1 1 . 


Error Numbers 


Num 


Messaqe 


Num 


Message 


0 


all e r rors 


46 


TOO BIG 


1 


WS FULL 


48 


name NOT COPIED 


2 


SYNTAX ERR 


49 


name NOT FOUND 


3 


UNDEFINED 


50 


name NOT ERASED 


4 


DOMAIN ERR 


51 


NOT GROUPED 


5 


RANK ERR 


52 


SEALED WS 


6 


LENGTH ERR 


53 


OLD WS , MUST EXPORT 


7 


INDEX ERR 


55 


NOT HELD 


8 


NO RESULT 


56 


ALREADY HELD 


10 


IMPLICIT ERR 


57 


NO SHARES 


11 


LIMIT ERR 


59 


HOLD ABORTED 


15 


SINGULAR MATRIX 


6 1 


HOLD DEADLOCK 


16 


FORMAT SYNTAX ERR 


62 


ENQ FULL 


20 


BAD CHAR 


68 


SV OUT A EXHAUSTED 


21 


LINESCAN ERR 


70 


FILE SPACE TOO LOW 


22 


TRUNCATED INPUT 


71 


FILE I/O ERROR fcg-Mxxxx-s 


23 


OPEN QUOTE 


72 


FILE DAMAGE 


30 


I/O ERR fcg-Mxxxx-s 


73 


FILE NAME ERR 


35 


DEFN ERR 


74 


NOT APL FILE 


36 


SI DAMAGE 


75 


FILE TBL FULL 


kO 


BAD COMMAND 


76 


FILE ACCESS ERR 


41 


NOT SAVED. THIS WS IS 


77 


FILE TIE ERR 


42 


FILE IN USE 


78 


PACKSET NOT MOUNTED 


43 


BAD FILE REF 


79 


FILE INDEX ERR 


44 


WS NOT FOUND 


80 


PACKAGE TOO BIG 


45 


TOO BIG TO LOAD 


100 


INTERRUPT 



Error Control Functions 



Table E-12. Error Control Functions 


Name 


Description 


r-^ UERF 
T* UERH 
UERL 
T* UERH 
Wx- UERN 
/X- UERP 

T UERS I 
T*- UERX 


Name of function involved in recent error. 
Description of most recent I/O error. 
Line executing most recent error. 
Error message for most recent error. 
Error number and line number of error. 
Index in UERL of error position. 
Signal error number / with error message T. 
Monitor code associated with I/O error. 
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Table E-13. CP-6 APL System Functions 


Name 


Descript ion 




UCPU 


CPU time used measured in milliseconds. 


Rt-W 


UCVT R 


Convert data R into type Wll] using 






W[Z] bits per item. 


/-^ 


DDL I 


Delay execution for at least / seconds. 




HEX H 


Erase objects named in H. 


V-*- 


UEXG If 


Erase global objects named in A^. 


V*- 


UP! T 


Convert character representation to number. 




QSRP N 


Return namelist of group members. 




UlBEX T 


Erase IBEX variable named in T. 


Tt- 


UIBLET H 


Return value of IBEX variable named in H. 


T 


UlBLET N 


Assign value T to IBEX variable named in N. 


R*- 


UIBNL 


Return names of current IBEX variables. 


R*- 


UIDLOC N 


Return name correspondence of each name in 






tf at each level of the state indicator. 


I"- 




APL invocation time in milliseconds. 


/-<- 


UIOK N 


Lock functions named in N. 


K"^ 


QNC tf 


Return name class of names in N. 


K*- 


QNCG H 


Return global name class of names in N. 




UtfL K 


Return names of objects of class K. 




WL K 


Like monadic UtfL but includes only names 






beginning with a letter in T. 




QONL 


Session mode: 0=batch, 1=onl ine. 




UOVH 


Processor overhead time in milliseconds. 




URN If 


Size in bytes of objects in tf . 


r 


UrinG- N 


Size in bytes of global objects in N. 




USCT 


Milliseconds elapsed since APL was invoked. 


Tt- 


USI 


Text vector containing result of )SI . 




QSITEID 


CP-6 site identifier. 




USITEtfAME 


Text vector containing CP-6 site name. 




USTEPCC I 


Sets value to use as step condition codes. 




USYSID 


Text vector containing current CP— 6 sysid. 




UUA 


8 item character vector of current account. 


I*- 


WL 


Number of CP— 6 system users. 




OVERS ION 


Version of the CP-6 APL processor. 




UVI T 


Indicate legal representations of numbers. 




[ffSID 


Text vector of the current workspace name. 



Shared Variable Functions 



Table E— 14. Shared Variable System Functions 


Name 


Descript ion 


/<- use 

C<- USVC N 

c*-c xysvc N 

/<- USVH T 
V<- USVO H 

vt-p USVO tf 

If-*- USVQ P 
V^ USVR H 
R<- USVS H 


Wait for a shared variable event. 
Obtain controls on shared variables in AT. 
Set controls on shared variables in N. 
Set current process identification to T. 
Obtain degree of coupling for names In N. 
Offer names in N to share with process P. 
Obtain names of shares not accepted. 
Retract names in from sharing. 
Shared variable states of names in A^. 
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File i/D 



File I/O functions may be used to access all CP-6 files provided access permission 
have been granted. 



Table E-15. File I/O Example Names 


Nome 


Desc r i pt i on 




f^P-^R nccAiint nr n fiH wifh n wifhin fh^ fil AnnmA 


f 




I 


Scalar integer dependent upon function. 


K 


Integer or character vector record identifier (key). 


L 


For INDEXed files: Numeric key matrix of shape (A^,3). 




Column 1 is the character index of the key start. 




column 2 is the key length and column 3 is 0 if 




duplicate keys are permitted. 


R 


Array dependent upon function. 


S 


Integer scalar file I/O stream number. 


T 


Integer record type 1=component ,2=datablock,3=raw. 


X 


Encryption seed (Integer or 4-item character vector). 


z 


Shape (y,17) character file access matrix. Columns 




1-8 contain accounts, 9 must be blank and 10-17 




contain Y or N for access control: READ, DELR, WNEW, 




UPDATE. DELF. NOLIST. REATTR and EXEC. 



Table E-16. File Functions 


Name 


Descr ipt ion 


R 


UFAPPEND S X T 


Add record or component to end of file. 


Kf-R 


UFAPPENDR S X T 


Some as UFAPPEND but returns key. 




UFCLEAR 


Close al 1 open f i les. 




UFCLOSE S 


Close streams in 5. 




UFCRPT S X 


Set default encryption seed. 




UFDEQ S K 


Release hold on file. 




DFDROP S K 


Delete record from file. 




UFENQ S K 


Hold a record. 




QFERASE S 


Close streams and delete files in 5. 




UFFLDS Y 


Return record field matrix. 




UFID S 


Return CP-6 file identifier for stream 5. 




UFKEYIST S I 


Set increment for UFAPPEND to keyed file. 




UFKEYS S 


Return matrix describing keys. 




QFLIB A 


Return names of files in account A. 




UFLIB A 


Return fids of type M in account A. 




UFHA 


Current file management account. 




mAHS 


Names of open files. 


R'>r 


UFNUMS 


Numbers of open files. 


F 


UFOPEN S 


Open file I/O stream. 




UFRDAC S 


Return access control matrix for file S. 


R* 


UFRDCI S K X 


Return component information. 


R*- 


UFREAD S K X T 


Read a record. 




UFRKEY S I 


Return key (1=f i rst ,2=current ,3=last) . 




UFSIZE S 


Return size of file S in bytes. 


Z 


UFSTAC S 


Set file access matrix. 


R 


UFVRITE S K X T 


Write a record or component. 
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Table E-17. File I/O Open Options 



Opt i on 



Description 



IN 

CREATE 
UPDATE 

NEWFILE 
OLDFILE 
ERROR 

NONE 

ALL 

SHARE IN 

NAMED 
SCRATCH 



DIRECT 
SEQUEN 

CTC 

LOAD 

COMP 

REASSIGN 



Open file for reading. 
Create a new file. 
Update an existing file. 

For create, always create a new file. 

For create, if file already exists use it. 

For create, if file exists report error. 

If UPDATE, open file for exclusive use, if 
IN, open shared with other IN, NONE users. 
Open file shared with multiple updaters. 
Open file shared with multiple readers. 

Create a permanent file. 
Create a scratch file. 



KEYED 


For 


c reate , 


spec 


fy 


f i le 


organizat ion 


CONSEC 


For 


c reate , 


spec 


fy 


f i le 


organizat Ion 


RANDOM 


For 


c reate , 


spec 


fy 


f i le 


organizat ion 


UR 


For 


c reate , 


spec 


fy 


file 


organ i zat i on 


RELATIVE 


For 


c reate , 


spec 


fy 


f i le 


organi zat ion 


INDEXED 


For 


c reate , 


spec 


fy 


f i le 


organ i zat i on 


CG 


For 


c reate , 


spec 


fy 


f i le 


organizat ion 


IREL 


For 


create , 


spec 


fy 


f i le 


organization 



Add file name to directory during open. 
Build record indices on INCLOSE. 
Request record compression. 
Use IBEX !SET for additional options. 



* indicates default. 



Text Editing Functions 

The right argument to these functions is a vector of text vectors. 



Table E-18. Text Editing Functions 


Name 


Description 


Ii-USCP T T2 
Tf-USRP T TR C\ CZ 

T*-UISSR T TS TR 

V*-USSS T TS 

M*-UTIX T SDV TDV DDV 

V*-UTLEX T SDV TDV DDV 


Compare strings T and 72. 

Replaces positions CI through C2 of string 

T with string TR. 

Replaces occurrences of string TS with 
string TR in string T. 

Returns indices of string TS in string T. 
Return matrix locating text lexemes. 
Return text lexemes. 
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I-D-S/II Functions 



Table E-19. I-D-S/II System Functions 


Name 


Descript ion 


R*-UDBACCEPT D 


Return db-key or area name. 


I*-nDBBUFFERS I 


Set number of buffers to use. 


I^UDBCHECK I 


Indicate a checkpoint. 


R*-UDBCONNECT D 


Connect a record to a set. 


QDBCRPT I 


Indicate an area encryption seed. 


R*-nDBDISCOt/(^ECT D 


Remove record from a set. 


R*-UDBERASE D 


Delete a record. 


R*-UDBFIND D 


Locate a record. 


R*-UDBFINISH D 


Close area(s). 


R^UDBFROM D 


Obtain data from workarea. 


R*-[]DBGET D 


Read a record from database. 


R*-UDBIF D 


Test for set membership. 


V*-UDBMEHBER D 


Return member indices of set or record. 


R*-QDBHODIFY D 


Re— write o record. 


T*-UDBHSG 


Return latest I— D— S/II error message. 


M*-UDBNAMES 


Names of all objects in current subschema. 


V*-UDBOVNER D 


Return owner indices of set or record. 


R^-UDBPRIVACY D 


Specify privacy locks. 


R*-UDBREADY D 


Open on area. 


Rf-UDBRETAIH D 


Indicate currencies to be retained. 


UDBROLL 


Roll back updates to last checkpoint. 


R'^UDBSTATS 


Report statistics. 


Rf-UDBSTATSOFF 


Turn statistics gathering off. 


R*-UDBSTATSON 


Turn statistics gathering on. 


R*-UDBSTORE D 


Write 0 new record. 


T*-UDBSUB T 


Indicate subschema name to use. 


R*-[]DBTO D 


Move data into work area. 


R*-UDBTRACEOH I 


Initiate I-D-S/II trace. 


R*-UDBTRACEOFF I 


Terminate I-D— S/II trace. 


R*-UDBTYPES 


Indicate types of objects in subschema. 


H*-UDBUSE V 


Namelist of use procedures for errors in V. 


V-f-N UDBUSE V 


Set use procedures associated with errors. 


Terminal Control 


System Functions 


Table E-20. Terminal System Functions 


Nome 


Descr i pt ion 


V<- UTATTR 


Return terminal attributes. 


UTECHO I 


Control terminal echo: 0soff,lBon. 


UTIN T 


Set input re-read line. 


R*! UTSQZ T 


Translate to or from mnemonics. 


DTTIHE I 


Set timeout on terminal reads. 


R^ UTWIHDOU 


Return terminal window locations and sizes. 
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Report Formatting Functions 



Table E-21 . UFMT Format Controls 


Po rni 




rilw 


Blank insertion 


rEw. s 


Exponential notation (scientific format) 


r qfw.d 


Fixed decimal notation 


r qC<text> 


Picture format 


r q /w 


I n t e^e r 


Tw 


Column tabbinQ 


r^w 


Blank insertion 


rijiexiij 


lexx inseriion 


rflt Avtn 

riji ex lu 


lexi insenion 


r"text" 


Text insertion 


r<text> 


Text insertion 


Where: 




r 


opt 1 ona 1 rep 1 1 cat i on count 


w 


loxui Tieiu wiuin 


s 


a 1^1X8 in A Torinui 


□ 




c 


CO 1 ufnn ui wnicn liic noxi i iciu wi i i siuri 




Ant 1 Arm 1 /iim 1 i f i Ar 
opx 1 unu 1 ifuu 111161 


Opt iona i qua 1 i f i ers 




B 


field is blonk if it Is exactly zero 


C 


insert comma between triods of digits 


L 


formatted field is left justified 


«<text> 


prefixes negative fields with text 


Ar<text> 


postfixes negative fields with text 


F<text> 


prefixes positive fields with text 


C<text> 


postfixes positive fields with text 


R<iexi> 


sets background for formatted value 


5<text> 


substitutions for •9Z*0_,.' 



Table E-22. Report Formatting Functions 


Name 


Descript ion 


H<-Q UFMT L 
UHDR T 

I*- UlfLS 
UPGE 
UVFC B 

T^X UXL T 


Format L according to specification 0. 
Set heading for output pages to f. 
Return lines remaining on output page. 
Begin future output on a new page. 
Set VFC character for next output line. 
Translate characters in T using vector X. 
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Bl ind i/0 Funct ions 



Blind I/O is provided to occess CP-6 devices using the special variables 0 through Q. 
The APL system command )SET is used to direct blind I/O to a particular device. 



Table E-23. Blind I/O Example Variable Names 


Nome 


Desc r i pt i on 


/ 


Integer scalar. 


J 


Optional integer scalar whose presence 




indicates a set mode operation and whose 




absence causes the current setting to be 




returned . 


K 


Scalar integer or character vector key. 


L 


Matrix of shape {H,M) where liiH^y and 




the following column meanings are assigned: 




1-field number, 2-line, 3-colunin, 4— length, 




5— attributes, 6-input attributes. 




7-initial value. 


S 


Blind I/O stream number (0 through 9). 


T 


Character vector. 


V 


Vector of form field numbers. 



Table E-24. Blind I/O Functions 


Name 


Description 


/-•- UBBIH S J 


Set or query binary I/O mode. 


UBCLOSE S I 


Close blind I/O stream S. 


L UBFLD S 


Define forms mode fields. 


K*- UBKEY S 


Key of current file position. 


Kt- UBKR S 


Key returned by last operation. 


Vt- UBLIHES S 


Return lines per page and lines remaining. 


L UBHFLD S 


Modify forms mode fields. 


UBPFILE S I 


Position to beginning or end of file. 


QBP RECORD S I 


Forward or backward space in file. 


UBREV S 


Rewi nd file or tape . 


UBREWRITE S J 


Set rewrite option. 


V UBRFLD S 


Release forms mode fields. 


UBRR S J 


Set re— read option. 


/<- UBRS S 


Size of record last read (F$DCB.ARS#) . 


QBSEED S I 


Set encryption seed. 


V UBSFLD S 


Select forms mode fields. 


It- UBSIZE S J 


Set read size. 


I'*- UBTRAHS S J 


Set or query transparency. 


/•^ UBVFC S J 


Set or query VFC. 


V UBXFLD S 


Expunge forms mode fields. 


WNSET S 


Return character vector containing CP— 6 
fid and )SET options. 
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Table E-25 


CP-6 APL 


Character 


Set 








Index 


APL 


ASCII 


Index 


APL 


ASCII 


Index 


APL 


ASCII 


Index 


APL 


ASCII 


e 




NUL 


64 


a 


0 


128 






192 


I 


$MIN 


1 




SOH 


65 


A 


A 


129 






193 


€ 


$E 


2 




STX 


66 


B 


B 


130 






194 






3 




ETX 


67 


C 


C 


131 






195 


L 


$DLT 


4 




EOT 


68 


D 


D 


132 






196 


I 


$1 


5 




ENQ 


69 


E 


E 


133 






197 


X 


# 


6 




ACK 


70 


F 


F 


134 






198 


■i- 


% 


7 




BEL 


71 


G 


G 


135 






199 


r 


$MAX 


8 




BS 


72 


H 


H 


136 






200 




$DRP 


9 




HT 


73 


I 


I 


137 






201 






10 




LF 


74 


J 


J 


138 






202 




$W 


1 1 




VT 


75 


K 


K 


139 






203 


z> 


$DSC 


12 




FF 


76 


L 


L 


140 






204 


A 


k 


13 




CR 


77 


H 


M 


141 






205 


V 


II 


14 




SO 


78 




N 


142 






206 




— 


15 




SI 


79 


0 


0 


143 






207 




$LE 


16 




DLE 


80 


P 


P 


144 






208 




$GE 


17 




DC1 


81 


Q 


Q 


145 






209 


V 


$0R 


18 




DC2 


82 


R 


R 


146 






210 


0 


$DMD 


19 




DC3 


83 


S 


S 


147 






211 




$LTK 


20 




DC4 


84 


T 


T 


148 






212 


-4 


$RTK 


21 




NAK 


85 


U 


U 


149 






213 


□ 


$0 


22 




SYN 


86 


V 


V 


150 






214 


0 


$0 


23 




ETB 


• 87 


w 


w 


151 






215 




$G0 


24 




CAN 


88 


X 


X 


152 






216 


*■ 





25 




EM 


89 


Y 


Y 


153 






217 


1 


$DCD 


26 




SUB 


90 


Z 


z 


154 






218 


T 


$ECD 


27 




ESC 


91 


[ 


[ 


155 






219 


a 


$C0M 


28 




FS 


92 


\ 


\ 


156 






220 




$EOV 


29 




GS 


93 


] 




Itak 


157 






221 




$NQV 


30 




RS 


94 


♦ 






158 






222 


I 


$FDI 


31 




US 


95 




$_ 


159 






223 


< 


$FND 


32 




BL 


96 


c 


$ENC 


160 






224 






33 


1 


! 


97 


A 


a 


161 


0 


$SC 


225 






34 




$" 


98 


B. 


b 


162 


/ 


$RD1 


226 






35 




$NE 


99 


Q 


c 


163 


u 


$CUP 


227 






36 


$ 


$ 


100 


H 


d 


164 


\ 


$XP1 


228 






37 


P 


$R 


101 


E 


e 


165 


t 


$GD 


229 






38 


n 


$CAP 


102 


E 


f 


166 




$LOK 


230 






39 


1 


' 


103 




g 


167 


t 


$XEC 


231 






40 


( 


( 


104 


K 


h 


168 


V 


$FMT 


232 






41 


) 


) 


105 


L 






169 


D 


$QQ 


233 






42 


* 


* 


106 


I 


j 


170 




$LOG 


234 






43 


+ 


+ 


107 


K 


k 


171 


e 


$RV1 


235 






44 


> 




108 


L 






172 


S 


$MDV 


236 






45 


- 


$- 


109 


a 


m 


173 


T 


$TBR 


237 






46 


• 




110 


n 


n 


174 


I 


$IB 


238 






47 


/ 


/ 


111 


a 


0 


175 


L 


$UDL 


239 






48 


0 


e 


112 


E 


P 


176 




$TPS 


240 






49 


1 


1 


113 


Q 


q 


177 


i 


$GU 


241 






50 


2 


2 


114 


E 


r 


178 


A 


$NND 


242 






51 


3 


3 


115 




s 


179 


V 


$NOR 


243 






52 




4 


116 


r 


t 


180 


<D 


$REV 


244 






53 


5 


5 


117 


a 


u 


181 


D 


$00 


245 






54 


6 


6 


118 


V 


V 


182 


HI 


$01 


246 






55 


7 


7 


119 


w 


w 


183 




$02 


247 






56 


8 


8 


120 




X 


184 


Q 


$03 


248 






57 


9 


9 


121 


r 


y 


185 




$04 


249 






58 


: 




122 


2 


z 


186 


Q 


$05 


250 






59 


S 




123 


1 






187 


G 


$06 


251 






60 


< 


< 


124 


1 






188 


Q 


$07 


252 






D 1 






125 


♦ 






189 


B 




ZOO 






62 


> 


> 


126 








190 


B 


$09 


254 






63 




? 


127 




DEL 


191 






255 
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Note: Index references indicate the page on which the paragraph containing the index 
term actually ends. Should the paragraph straddle two pages, the actual indexed term 
might be on the first page, while the index reference is to the second page. 



A Programming Language - 1—1 
abort - 6-2 7-20 7-21 10-2 
Absolute value function - 3-17 5-10 
access control vector — 11—26 
access controls - 12-13 
Accessing Data - 13—6 
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account - 3-4 11-22 11-25 11-28 12-18 
Active Workspace - 8-2 11-25 
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saving - 8-3 8-13 8-34 8-35 
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Additional System Functions — A— 7 
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And function - 3-20 5-16 5-45 A-6 

APL Character Set. CP-6 - B-1 

APL Exponential Notation — 3-2 

APL Functions and Operators — 3—14 

APL Input and Output - A-2 

APL invocation options - 8-3 

APL Standards Compatibility - 1-1 

APL typewheel - 2-1 

append record to a file - 12-8 

arccos - 5-11 A-2 

arccosh - 3-18 5-11 A-2 

a res in - 3-18 5-11 A-2 

arcsinh - 3-18 5-11 A-2 

arctan - 3-18 5-11 A-2 

arctanh - 3-18 5-11 A-2 

Argument characteristics - 5-1 

Arithmetic Functions — 5-3 

Arithmetic Limits — A— 1 

Array Limi ts - A-1 

Array Representation — A— 5 

array — 

depth - 3-13 3-28 5-22 

nested - 3-13 3-43 5-2 

prototype - 3-26 3-44 5-39 5-39 

rank - 3-8 3-13 3-35 5-2 

shape - 3-8 3-13 3-23 3-35 5-2 5-26 
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simple — 3-13 3—43 

type - 3-13 3-26 3-35 5-40 
arrays - 2-7 3-8 3-13 
Arrays and Indexing - 3-8 
Arrays of two or more dimensions — 3-42 
ascending order - 3-23 5-31 
ASCII - B-1 

assigning a value to an array - 3-11 
Assignment — 3—5 3-36 

Assignment and Non-assignment Statements - 6-5 
Assignment control - 1-1 
assignment statements - 6-5 
aster i sk - 7-21 

DAT System Function (Function Attributes) - 7-28 E-6 
atomic vector - 11-6 B-1 
ottent ion - 3-44 

UAV Function (Atomic Vector) - 11-6 E-4 
Axis Operator - 3-14 11-2 



Bare output - 3-44 
bose value - 3—25 5-34 
Batch - 1-1 3-38 11-16 

DBBItf Function (Set and Query Binary Mode} - 16-4 E-13 
UBCLOSE Function (Close Blind I/O Channel) - 16-10 E-13 
UBDELREC Function (Delete Record) - 16-11 
best fit - 3-29 5-43 

UBFLD Function (Field Definition) - 16-14 E-13 
bi nary I/O - 1 6-4 
BINARY MODE - 16-4 

Binomial function - 3-18 5-12 5-45 A-3 
UBKEY Function (Return Key) - 16-6 E-13 
UBKR Function (Key Returned) - 16-10 E-13 
BI ind I/O - 1-1 3-38 A-7 
Blind I/O Functions - E-13 
Blind I/O on a Device - 16-2 
Blind I/O System Functions - 16-4 
BI ind I/O - 

binary mode — 16-4 

close I/O channel - 16-10 

current key — 16-6 

delete record — 16—11 

field definition - 16-14 

field erase — 16-18 

field modification - 16—16 

field selection - 16-17 

last key returned - 16—10 

lines of output - 16-6 

position file — 16—7 

position record - 16-7 

previous record size - 16—9 

read size - 16-5 

record encryption — 16—8 

release field - 16—18 

return DCB setting - 16-12 

rewind - 16-8 

rewrite record - 16-8 

skip to new page - 16-11 

terminal re— read — 16-9 

transparent mode — 16-6 

uses - 16-1 

VFC - 16-5 
Blind Input/Output - 1-2 
blind output — 3—44 

UBLItfES Function (Lines Remaining) - 16-6 E-13 
UBMFLD Function (Modify Field) - 16-16 E-13 
body of a function — 7-2 7—5 
UBPAGE Function (Skip to New Page) - 16-11 
UBPFILE Function (Position File) - 16-7 E-13 
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QBPRECORD Function (Position Record) - 16-7 E-13 
branch - 6-6 7-20 7-21 10-2 
Branch Statements - 6-2 

break - 3-44 4-3 7-20 8-30 8-30 8-36 10-1 

BREAK key - 8-29 

break response - 8-29 8-36 

UBREW Function (Rewind) - 16-8 E-13 

UBREWRITE Function (Rewrite Record) - 16-8 E~13 

UBRFLD Function (Release Field) - 16-18 E-13 

UBRR Function (Re-Read Mode) - 16-9 E-13 

UBRS Function (Record Size) - 16-9 E-13 

UBSEED Function (Encryption Seed) - 16-8 E-13 

UBSFLD Function (Select Field) - 16-17 E-13 

UBSIZE Function (Read Size) - 16-5 E-13 

UBTRANS Function (Set and Query Transparency) - 16-6 E-13 
UBVFC Function (Set and Query VFC) - 16-5 E-13 
UBXFLD Function (Expunge Field) - 16-18 E-13 
byte keys - 16-7 



canonical representation — 7—26 7—27 11—4 A— 7 

)CATCH Intercepting Assignments - 1-3 8-4 8-10 8-10 8-13 

Catching assignments — 1—3 

Catenation function - 3-14 3-23 5-23 14-1 A-6 
Ceiling function - 3-17 5-8 11-2 
Changing a Function Header - 7—17 
changing a line - 7-15 

Changing Assignments of Input/Output Streams - 8-35 
Changing Input/Output assignments - 8-35 
Changing Suspended Functions - 7—6 

character - 2-7 3-2 3-5 3-13 3-42 5-31 5-33 5-40 5-41 A-6 

Character Constants — 3—2 

Character Set - 2-2 11-6 B-1 

character vectors - 3—42 

Circular function - 3-18 5-11 5-45 

classification of functions — 3—35 

)CLEAR Clearing Workspace - 3-40 5-42 7-19 8-4 8-11 8-13 8-13 11-3 12-1 13-10 

Clearing the state indicator — 8-37 

Clearing Workspace — 8-13 

close blind I/O chonnel - 16-10 

closing f i les - 12-6 

colon - 6—4 

Combination function - 3-18 5-12 A-3 
Commend Processor - 8—4 8-35 
Comment Statements — 6-1 
Comments - 2-6 6-1 

Communicating with computer center operator - 8-30 
Communicating with operator - 8-30 
Communication Commands — 8-6 

comporison tolerance - 3-42 5-13 5-22 11-2 A-1 A-6 A-8 

component information - 12—1 12-11 

component records — 12—1 

Compound statements - 1-2 6-6 

Compression A/ Operator (Replicate) - 5-47 

Compression along the first coordinate — 3-32 

Compression operator - 3-31 5-47 5—48 A-6 

Conjugate function - 3-14 5-4 A-6 

connecting to the CP-6 system - 2-1 

Considerations after Gaining o Sidetrock - 10-9 

Consistent Extensions to the ISO APL Standard - A-5 

Constants — 3—1 

CONTINUE Saving Active Workspace and Leaving APL - 3-40 7-19 8-6 8-13 

CONTINUE HOLD - 3-40 
Continue Workspace - 8-3 
Control Keys - 2-6 

Controlling the state indicator - 8-36 

Conversion - 1 1-7 

convert data - 11—7 

Coordinating Shared Files - 12-14 
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)COPY Copying from Saved Workspace - 1-2 7-1 7-19 7-21 8-4 8-15 8-22 10-5 A-8 

Copying from saved workspace - 8-15 8-31 8-33 

corrections - 2-3 

cosine - 3-18 5-11 A-2 

CP-6 APL Character Set - B-2 

CP-6 APL System Functions - E-8 

CP-6 APL version - 11-24 

CP-6 Dependent Algorithms - A-4 

CP-6 faci I ities, avoi lobi I ity of others - 1-2 

CP-6 site id - 11-20 

CP-6 sitename - 11-20 

CP-6 sysid - 11-21 

QCPU Function (CPU Time Used) - 11-7 E-8 
CPU Time Used - 11-7 11-17 

UCR System Function (Canonicoi Representation) - 7-26 E-6 
creating a group - 8-22 

DOT Variable (Comparison Tolerance) - 11-2 8-13 A-1 E-4 

current DCB setting - 16-12 

current time — 11-21 

UCVT Function (Convert) - 11-7 E-8 



Database access — 1-3 
datablock records - 12-1 

UDBACCEPT Function (Return db-key or Area Name) - E-1 1 

UDBANLZ Function (Analyze Subschema Names) - 13-5 

UDBBUFFERS Function (Set Number of Buffers) - E-1 1 

QDBCHECK Function (Indicate a Checkpoint) - E-1 1 

UDBCONHECT Function (Connect Record to Set) - E-11 

UDBCRPT Function (Indicate an Area Encryption Seed) - E-11 

UDBDISCONHECT Function (Remove Record from Set) - E-11 

UDBERASE Function (Delete a Record) - E-11 

QDBFIHD Function (Locote a Record) - E-11 

UDBFItflSH Function (Close Area(s)) - E-11 

UDBFROH Function (Retrieving Data) - 13-7 E-11 

□ZJSCrr Function (Read a Record from Database) - E-11 

UDBIF Function (Test for Set Membership) - E-11 

QDBIf/FORM Function (Dotabase Register) - 13-6 

UDBHEMBER Function (Set Member) - 13-5 E-11 

UDBMODIFY Function (Re-write a Record) - E-11 

UDBMSG Function (Return Latest I-D-S/II Error Message) - E-11 

UDBNAMES Function (List Subschema Names) - 13-2 E-11 

UDBOWtiER Function (Set Owner) - 13-5 E-11 

UDBPRIVACY Function (Specify Privacy Locks) - E-11 

UDBREADY Function (Open an Area) - E-11 

UDBRETAIN Function (Indicate Currencies to be Retained) - E-11 

UDBROLL Function (Roll Back Updates) - E-11 

^BSTATS Function (Report Statistics) - E-11 

UDBSTATSOFF Function (Turn Statistics Gathering Off) - E-11 

UDBSTATSOH Function (Turn Statistics Gathering On) - E-11 

DBSTATUS - 13-9 

UDBSTORE Function (Write a New Record) - E-11 
QDBSUB Function (Identify Subschema) - E-11 
UDBTO Function (Storing Data) - 13-7 E-11 
UDBTRACEOFF Function (Stop I-D-S/II Trace} - E-11 
UDBTRACEON Function (Start I-D-S/II Trace) - E-11 
UDBTYPES Function (Subschema Nome Types) - 13-2 E-11 
UDBUSE Function (Use Procedures) - 13-9 E-11 
DCB name - 16-12 

Deal function - 3-24 5-19 8-31 11-2 11-3 A-4 A-6 
Debugging Aid for Intercepting Assignments - 8-10 
Decode function - 5-34 
Default Output - 4-2 
define from package - 14-5 
Defined Function Controls - E-6 
Defined Function References - 3-35 
Defined Functions - 2-7 7-1 A-2 

examples - 7-2 

syntax — 7-2 



1-4 



Index 



CE38-03 



definition mode — 2—4 

degree of coupling - 11-25 11-27 11-29 

del - 7-1 

Delay - 11-8 

delay execution - 11-8 

Delay function - A-7 

Deleting a Line - 7-12 

delet ing - 

file- 12-7 

function line - 7-12 

IBEX variable - 11-11 

I i ne - 2-3 7-1 1 

record from file - 12-10 

saved workspace — 8—17 

variables, functions - 11—8 

variables, functions and groups - 8-19 
depth - 3-13 

Depth function - 3-28 5-22 
derived function - 3—13 4-2 
descending order - 3—24 5—33 
Diablo 1620 - 2-1 
diamond - 1-2 5-42 6-6 

)DIGITS Specifying Numeric Print Precision - 2-3 2-4 3-42 8-5 8-16 

Dimension function - 5-26 

Di rect Input - 3-39 

Direct-Line Prompt - 2-5 

Directives - 7-6 E-6 

Disclose function - 3-27 5-21 A-5 

Display - 

f unct i on - 7-8 

i ndex origin - 8—31 
Displaying a Range of Lines — 7—9 
Displaying All Lines - 7—8 
Displaying Lines Containing a String — 7—10 
Displaying One Line - 7-9 

Displaying the Next Occurrence of a String — 7-10 
Displaying User-defined Functions - 7-8 
d i v i s i on - 3-42 

Division function — 3—15 5—6 5—45 
HDL Function (Delay) - 11-8 E-8 
domain — 3—35 5-1 
domain tables - 5-1 

)DROP Dropping a Saved Workspace - 8-5 8-17 A-8 

Drop function - 3-26 5-40 

Dropping a saved workspace — 8—17 

Dummies - 3—5 7—4 

Dyadic - 3-13 3-35 7-2 

Dyadic format - 3-25 

dyadic function — 3-13 5-1 5-46 

Dyadic functions with explicit result — 7—2 

Dyadic functions with no explicit result - 7-2 

dyadic scalar functions — 3—30 5-2 

Dyadic Shared Variable Control - 11-26 

Dyadic Shared Variable Offer - 11-27 

Dyadic transpose function - 3-29 11-2 

Dynamics of Sidetrocking - 10-8 



e - 3-15 5-7 5-8 A-3 

Each operator - 3-35 5-53 A— 7 

Easy function copying - 1-2 

Echoing of input - 8-36 

Editing a line number - 7-17 

editing defined functions — 5-42 

Editing User-defined Functions - 7-11 

)EDITOR Selecting the APL Function Editor - 8-7 8-18 

empty array - 3-8 3-43 

Enclose function - 3-27 5-20 14-1 A-5 

Encode function - 3-25 5-35 



CE38-03 



Index 



i-5 



encrypt i on - 16—8 

encryption seed - 12-1 16-4 

)END Exiting APL - 8-7 8-19 11-3 

Equals function - 3-19 5-14 5-46 11-2 

Equivalence function - 3-28 5-22 11-2 A-5 

)ERASE Deleting Objects from Active Workspace - 7-19 7-21 8-5 8-19 8-22 14-1 A-8 

UERF Function (Error Function) - 10-10 E-7 

UERH Function (Error Help) - 10-11 E-7 

UERL Function (Error Line) - 10-11 E-7 

UERM Function (Error Message) - 10-10 E-7 

UERN Function (Error Number) - 10-10 E-7 

UERP Function (Error Position) - 10-11 E-7 

)ERROR Selecting Error Message Information Level - 8-7 8-20 

Error and Break control - 1—3 

ERROR CONTROL - 10-4 10-7 

Error Control Functions— E— 7 

Error Stop - 10-3 

Errors and Breaks - 4-3 

Errors on Input or Output - 8—36 

UERS Function (Error Simulation) - 10-12 10-4 E-7 

UERX Function (I/O Error) - 10-11 E-7 

Evaluated Input - 3-39 6-6 7-1 A-2 

UEX Function (Expunge) - 11-8 14-1 E-8 

Examples of Defined Functions — 7—2 

Execute - 3-27 

Execute function - 1-3 3-26 5-41 6-6 7-1 10-5 A-6 

executing defined functions - 7-20 

Execution and Definition Modes - 2—4 

Execution Break - 10-1 

execution mode — 2-4 

execution time - 11—7 11—17 

OEXG Function (Expunge Globals) - 11-9 E-8 

exiting APL - 8-13 8-19 

Expansion along the first coordinate — 3-34 
Expansion A\ Operator — 5—49 
Expansion operator - 3-34 5—49 A-6 
Exponential function - 3—15 5-7 A— 3 
exponential notation — 3—2 

Exponentiation function — 3—15 3—16 5—7 5-45 A— 3 
expression evaluation - 4—1 
expunge - 8-19 11-8 11-9 
Expunge Global - 11—9 
expunge IBEX variable - 11-11 
Expunge names - 14-7 
Extensions to Defined Functions - A-8 
Extensions to Primitive Functions — A-6 
Extensions to Primitive Operators — A— 7 
Extensions to System Commands - A-8 
Extensions to System Functions - A— 7 
Extensions to System Variables - A-8 



Factorial function - 3-17 5—12 

UFAPPEND Function (Append Record to File) - 12-8 E-9 
UFAPPENDR - 12-8 E-9 

UFCLEAR Function fClose All Open Files) - 12-7 E-9 
UFCLOSE Function (Closing and Renaming Files) - 12-6 E-9 
UFCRPT Function (Set File Encryption Seed) - 12-17 E-9 
UFDEQ Function (Release Record or File) - 12-14 E-9 
UFDROP Function (Delete Record from File) - 12-10 E-9 
UFEffQ Function (Hold a Record) - 12-14 E-9 
DFERASE Function (Close and Delete File) - 12-7 E-9 
QFFLDS Function (Return Record Fields) - 12-22 E-9 
UFI Function (Fix Input) - 11-9 E-8 
fid - 3-3 3-4 12-4 12-4 

UFID Function (File Identifier) - 12-4 E-9 
Field Definition Matrix - 16-13 
Field Definition Matrix Columns - 16-13 
file- A-7 



i-6 



Index 



CE38-03 



File Access Controls - 12-11 

File Access Matrix - 12-12 

Fi le I/O - 1-1 12-1 E-9 

file identifier - 3-4 12-4 

File Information Functions — 12—3 

File Input/Output - 1-1 12-1 

File Management Account — 12-18 

file output - 12-10 

File Status Functions - 12-15 

Fi le System - A-2 

f i le - 

access control - 12-2 
access matrix - 12-11 
closing - 12-6 12-7 
component information - 12-11 
component records - 12-1 12-11 
creation - 12-4 12-23 
data encryption - 12-1 
datoblock records — 12—1 
delete record - 12—10 
delet ing - 12-7 
encryption - 16-8 
f unct i ons - E-9 
indexed files - 12-23 
input - 12-9 
key - 12-1 

key information - 12—16 
list library file names - 12—18 
modification - 12-6 12-23 
names of open files - 12-3 
non-APL records — 12-1 
numbers of open files - 12-3 
open options - E— 10 
opening - 12-4 
reodi ng - 1 6-3 

record field descriptions — 12—20 
record identifier - 12—1 
record types - 12-1 
rename - 12-6 

return file access matrix - 12—12 
return key - 12-15 16-6 16-10 
return record field definitions — 12—21 
set file access matrix — 12—13 
shar i ng - 12-14 
size - 12-16 
stream number — 12—1 
writing - 12-8 12-10 16-3 
f i les - A-2 

First function - 3-26 5-39 A-5 
fix input - 11-9 

UFKEYINT Function (Set Key Interval) - 12-16 E-9 
UFKEYS Function (Return File Keys} - 12-16 E-9 
UFLIB Function (Return File Names) - 12-18 
UFLIB Function (Return Library File Names) - E-9 
Floor function - 3-16 5-9 11-2 

{]FHA Function (Return File Management Account) - 12—18 E— 9 

UFHT Format Controls - 9-1 E-12 E-12 

UFNAMS Function (Names of Open Files) - 12-3 E-9 

)FNS Listing Global Function Names - 8-7 8-21 10-1 A-8 

UFNUHS Function (Numbers of Open Files) - 12-3 E-9 

UFOPEN Function (Open File) - 12-24 12-4 E-9 

Format Controls, Report - E— 12 

Format Data List (Right Argument) - 9-2 

Format Error Reports - 9-7 

Format function - 1-1 3-25 5-37 9-1 11-3 

Format Qualifier and Affixture Codes - 9-6 

Format Resul t - 9-7 

Format Specifications - 9—1 

Format Specifications versus Data Types — 9-2 
Format Statement (Left Argument) - 9-2 



CE38-03 



Index 



1-7 



Format Symbol Substitution - 9-7 

Formatted output - 1-1 

Formatting a Vector on One Line - 9—4 

Formatting Aids — 9—8 

Formatting Matrix Arguments - 9-4 

Formatting Scalar Arguments — 9-3 

Formatting Vector Arguments - 9—3 

Forms Mode - 16-12 

Forms of Output Values - 9-5 

fractional number - 3-41 

UFRDAC Function fReturn File Access Matrix) - 12-12 E-9 
UFRDCI Function (Return Component Information) - 12-11 E-9 
UFREAD Function (Read a Record) - 12-9 E-9 
UFRKEY Function (Return Key Values) - 12-15 E-9 
UFSIZE Function (File Size) - 12-16 E-9 
UFSTAC Function (Store File Access Controls) - 12-13 E-9 
Ion (Absolute Value, Residue) - 5-10 
(And, LCM) - 5-16 
(Base Value, Decode) - 5—34 
(Ceiling, Maximum) - 5-8 
(Conjugate, Addition) - 5—4 
(Depth, Equivalence) - 5—22 
(Disclose, Pick) - 5-21 
(Drop) - 5-40 
(Enclose) - 5-20 
(Equals) - 5-14 
(Execute) - 5—41 

(Exponential, Exponentiation) — 5—7 
(Factorial, Binomial) - 5—12 
(First. Take) - 5-39 
(Floor, Minimum) — 5—9 
(Format) - 5-37 
(Grade-Down) - 5-33 
(Grade-up) - 5-31 
(Greater Than or Equal) — 5—14 
(Greater Than) — 5—15 
(Index Generator, Index Of) - 5-19 
(Less Than or Equal) — 5—13 
(Less Than) - 5—13 

(Matrix Inverse, Matrix Divide) — 5—43 
(Nand) - 5-17 

(Natural Logarithm, Logarithm) - 5-8 
(Negate, Subtraction) - 5—4 
(Nor) - 5-18 
(Not Equal) - 5-15 
(Not) - 5-18 
(Or. GOD) - 5-16 
(Pi Times, Circulor) — 5—11 
(Ravel, Catenation. Lamination) — 5-23 
(Reciprocal. Division) - 5-6 
(Representation, Encode) — 5—35 
(Reversal. Rotation) - 5-26 
(Rol I . Deal) - 5-19 
(Shape. Reshape) - 5-26 
(Signum. Multiplication) — 5-5 
(Transpose) - 5—27 
(Type. Membership) — 5—40 
r-28 



- 8-21 



Function-Line Prompt - 2-5 
f unct i on - 
body - 7-2 

creation - 7-2 7-27 A-7 
display - 7-26 
display one line — 7-9 



1-8 



Index 



CE38-03 



displaying - 7—8 

edi t i ng I i nes - 7-1 1 

header - 3-35 7-1 11-4 A-8 

header modification — 7—17 

line deletion - 7-12 

line insertion — 7-13 

line modification — 7—15 

line replacement - 7—14 

locking - 7-22 7-27 11-4 14-7 

sidet raciti ng - 10-4 10-7 

stop controls - 7-25 10-2 11-5 A-7 

stop display - 8-33 

suspended — 3-36 

trace - 7-23 8-27 11-5 A-4 A-7 
functions - 2-7 3-13 A-8 
Functions and Arguments - 3-13 
Functions — 

Defined - A-2 

dyadic - 3—13 

Logical - E-2 

Mixed - E-3 

monodic - 3-13 

Relatione I - E-2 

Scaler Dyadic - E-1 

Scalar Monadic - E-1 
UFVRITE Function (Write or Replace a Record) - 12-10 E-9 
UFX System Function (Fi x Def i ni t ion) - 7-27 E-6 



GCD f unct ion - 5-16 
General APL Input - 2-2 
General Input/Output - 3-39 
Generalized combination function — 3—17 
Generalized factorial function - 3-17 
Generalized inner product function — 3-32 
Generalized outer product function — 3—33 
global function names — 8—21 
Global Name Classification - 11-15 
Global Room - 11-18 

Global Variable Names, Listing — 8—41 

global variables — 3—6 

)G0 Resume Execution - 8-7 8-21 

Grade-down function - 1-4 3-24 8-31 11-2 A-5 A-6 

Grade-up function - 1-4 3-23 8-31 11-2 A-5 A-6 

graphics — A-7 

Graphics Attribute Variables - 15-20 

Graphics Control Functions and Variables — 15-41 

Graphics Output Functions — 15-2 

Graphics Segment Functions - 15-10 

Graphics Viewing Variables - 15-30 

\yiRBACKGROUND Variable (Background Index) - 15-53 

UGRBATCH Function (Control Batching of Updates) - 15-48 

UGRBCLIP Variable (Back Plane Clipping) - 15-38 

UORCAPABILITIES Function (Inquire Capabilities) - 15-44 

UGRCHJUST Variable (Character Justification) - 15-28 

UQRCHPATH Variable (Character Path) - 15-27 

UGRCHPLAtfE Variable (Character Plane) - 15-26 

UGRCHPREC Variable (Character Precision) - 15-28 

UGRCHSIZE Variable (Character Size) - 15-25 

UGRCHSPACE Variable (Character Space) - 15-27 

nCRCHUP Variable (Character Up) - 15-26 

UGRCLIP Variable (Window Clipping) - 15-37 

QGRCOLINDEX Function (Set/Inquire Color Indices) - 15-51 

DGRCOLMODEL Function (Color Model) - 15-50 

DGRCOORD Variable (Coordinate System Type) - 15-39 

[yjRCP Function (Current Position) - 15-10 

QGRCSTATUS Function (Inquire Control Status) - 15-49 

[y^RCURREtfT Function (Moke Picture Current) - 15-48 

QGRDONE Function (Terminate APL Graphics) - 15-42 



CE38-03 



Index 



i-9 



UGRDRAW Function (Draw Picture) - 15-5 
Greater Than function - 3-19 5-15 5-46 11-2 
Greater Than or Equal function - 3-19 5-14 5-46 11-2 
Greatest Common Divisor Function — 1—4 3-21 A— 6 
DGRFCLJP Variable (Front Plane Clipping) - 15-38 
OG/?r/LL Variable (Fill Index) - 15-29 
UCRFONT Voriable (Font) - 15-24 
\yiRFRAME Function (New Frame) - 15-50 

DGRHIGHLIGHT Variable (Set/Inquire Highlighting) - 15-19 

DGRIHMVISIBILITY Function (Immediate Visibility) - 15-47 

UORItfIT Function (Initialize APL Graphics) - 15-41 

UGRIlflTSURF Function (Initialize View Surface) - 15-42 

DCRIIfTINDEX Function (Set/Inquire Intensity Indices) - 15-52 

DCRLI Variable (Line Index) - 15-23 

UGRLIHE Function (Draw Line) - 15-3 

UGRLS Variable (Line Style) - 15-23 

UORLU Variable (Line Width) - 15-22 

UGRMARK Function (Draw Marker Symbols) - 15-3 

UGRMARKER Variable (Marker Symbol) - 15-21 

UORNDC Function (Map to NDC) - 15-8 

)GROUP Creating a Group - 8-5 8-22 

Group, Listing Members of a - 8-23 11-10 

groups - 3-4 11-10 

)GRP Listing Members of a Group - 8-7 8-23 

UGRP Function (Return Group Members) - 11-10 E-8 

UGRPEH Variable (Pen) - 15-24 

UORPES Variable (Polygon Edge Style) - 15-22 

UGRPINS Variable (Polygon Interior Style) - 15-21 

UGRPIXEL Variable (Pixel Array) - 15-53 

UORPIXELORG Variable (Pixel Pattern Origin) - 15-54 

UGRPOLYGOtf Function (Draw Polygon) - 15-4 

[}GRPROJECTIOtf Variable (Projection Type) - 15-36 

)GRPS Listing Names of Groups - 8-8 8-24 10-1 

UGRSEGCLOSE Function (Close Retained Segment) - 15-11 

UGRSEGCURR Function (Inquire Open Segment) - 15-15 

QGRSEGDEL Function (Delete Retained Segment) - 15-12 

UGRSEGHIGHLIGHT Function (Segment Highlight) - 15-18 

UGRSEGOPEH Function (Create o Retained Segment) - 15-10 

UGRSEGREH Function (Rename Retained Segment) - 15-13 

UGRSEGS Function (Inquire Retained Segment Names) — 15-14 

UGRSEGSURFS Function (Inquire Segment Surfaces) - 15-13 

UGRSEGVISIBILITY Function (Segment Visibility) - 15-17 

UGRSPACE Variable (NDC Space) - 15-31 

UGRSURFACE Function (Select View Surface) - 15-45 

UGRSURFACES Function (Inquire Selected Surfaces) - 15-47 

UGRTERMSURF Function (Terminate View Surface) - 15-43 

DGRTEXT Function (Draw Text) - 15-6 

UGRTEXTI Variable (Text Index) - 15-25 

DGRTEXTX Function (Inquire Text Extent) - 15-9 

UGRTSEG Function (Inquire Open Temporary Segment) - 15—16 

UGRTSEGC Function (Close Temporary Segment) - 15-16 

UGRTSEGO Function (Create Temporary Segment) - 15-15 

UGRUtfSURFACE Function (Deselect View Surface) - 15-46 

DGRUP Variable (View Up) - 15-31 

DGRVDEPTH Variable (View Depth) - 15-35 

UGRVERTEX Variable (Vertex Indices) - 15-29 

[]GRVIEVPORT Variable (Viewport) - 15-32 

UGRVrsiBILITY Variable (Set/Inquire Visibility) - 15-19 

UGRVPLNDIS Variable (View Plane Distance) - 15-34 

DGRVPLNORM Variable (View Plane Normal) - 15-34 

DGRVREFPT Variable (View Reference Point) - 15-33 

DGRWINDOW Variable (Window) - 15-30 

DGRWORLD Variable (World Transformation) - 15-40 

DGRWORLDC Function (Map to World Coordinates) - 15-7 



i-10 



Index 



CE38-03 



UHDR Function (Set Page Heading) - 9-8 E-12 

header - 3-35 7-1 7-17 11-4 A-8 

header of a function — 7—2 

higher— order array - 3—8 

hold a f i le - 12-14 

hyperbolic cosine — 3—18 5-11 A— 2 

hyperbolic sine - 3—18 5-11 A— 2 

hyperbolic tangent - 3-18 5-11 A— 2 



I— beam function — A— 5 

I-D-S/II Error Reporting and Handling - 13-9 
I-D-S/II Function Arguments — 13—4 
I-D-S/II Functions - E-11 
I-D-S/II - 

list name — 13—2 

list name types — 13-2 

lookup names - 13-5 

retrieving data — 13-7 

system functions — A-7 

use procedures - 13-9 
)IBEX Issuing CP-6 Commands - 8-8 8-24 
QIBEX Function (IBEX Expunge) - 11-11 E-8 
IBEX - 

variable - 11-11 11-12 
DIBLET Function (Set/Query IBEX Variable) - 11-11 E-8 
UIBHL Function (IBEX Name list) - 11-12 E-8 
identifier location - 11-12 
Identifying active workspace — 8—43 
UIDLOC Function (Identifier Location) - 11-12 E-8 
immediate execution - 2-4 A-2 
Implementation Defined System Variables - A-2 
Index generator function - 3-22 5-19 8-31 11-2 A-6 
Index of function - 3-22 5-19 8-31 11-2 14-1 
index origin - 3-22 3-37 5-19 8-31 11-2 A-1 A-8 
Index Origin. Setting - 8-31 
Indexed Assignment — 3-37 
indexing - 8—31 14-1 A-6 
Indexing an Indexed Argument — 3—12 
Indexing of Arrays - 3-9 
information level - 8-20 
Initiating on APL Session - 8-3 
Inner product - 3-32 5-50 
Inner Product f.g Operator - 5-50 
Input Types - 

b I i nd - 3-39 

d t rect - 3-39 

evaluated — 3-39 

quote quad — 3-39 
Input. APL - 2-2 
Input/Output - 3-38 

Input/Output Assignment Control - 1-1 8-3 8-35 
Input/Output Devices - 3-38 

Input/Output streams, changing assignments — 8-35 
Inquiry Commands - 8—6 
Insert Pacl<age - 14-3 
Inserting a Line - 7-13 
integer - 3-1 

intercepting assignments - 8—10 

Intermediate results, observation of — 1-3 

interrupt — 3—44 

Inverse cosine - 3-18 5-11 A— 2 

Inverse function - 3-27 

Inverse hyperbolic cosine - 3-18 5-11 A-2 
inverse hyperbolic sine - 3-18 5-11 A-2 
Inverse hyperbolic tangent - 3—18 5—11 A-2 
inverse sine — 3-18 5-11 A— 2 



CE38-03 



Index 



i-11 



inverse tangent - 3-18 5-11 A-2 

Invocation of the CP-6 Command Processor - 8-24 

Invoking APL - 8-3 

UIO Variable (Index Origin) - 11-2 8-13 E-4 
Issuing Multiple Directives - 7—15 
Issuing System Commands — 7—19 
i tern - 3-8 

Items Subject to Sidetracking - 10-6 



J 



Join function - 3-23 5-23 14-1 A-6 



K 



key - 12-15 12-16 16-6 16-10 



L 



Labels - 3-4 3-5 6-4 7-4 7-5 

Lamination function — 5—23 

latent expression - 8-26 11-2 A-1 

ULC Function (Line Chain) - 11-13 7-21 E-4 

LCM - 5-16 

Least Common Multiple Function — 1—4 3—20 A-6 
least squares fit - 3-29 5—43 
leaving APL - 8-13 8-32 
left argument - 3-35 
length — 5—1 

Less than function - 3-18 5-13 5-46 11-2 

Less than or equal function - 3-19 5-13 5—46 11—2 

ULGT Function (Logon Time) - 11-14 E-8 

)LIB Listing Names of Saved Workspaces - 8-8 8-25 10-1 A-8 



brary - 12-18 
brary or Account Information — 12—18 
brary workspace - 7—1 8-2 
ne Corrections during Input — 2-3 
ne counter - 7-21 
ne numbers - 7-14 
ne numbers in execution - 11—13 
ne width setting - 8-42 
sti.ng function names - 8-21 
sting global variable names - 8-41 
sting Group Names - 8-24 
sting Members of a Group - 11-10 
sting names of saved workspaces — 8—25 
sting the Members of a Group - 8-23 
sting the State Indicator - 8-38 
st i ng — 

active workspace name — 8-43 11—25 

current DCB setting - 16-12 

file access matrix — 12-12 

file keys - 12-15 12-16 

file names and members - 12-3 

files in account — 12—18 

global function names - 8-21 

global names - 8-27 

global variable names - 8-41 

group members - 8-23 11-10 

group names - 8—24 

IBEX variable - 11-12 

names — 11—15 

package names — 14—3 

platen width - 8-42 

print precision - 8—16 

saved workspaces - 8-25 

state indicator - 7-20 8-36 

state indicator lines — 8—38 



i-12 



Index 



CE38-03 



storage requirements - 11—17 
workspace available — 11—24 
I iterals - 3-2 

)LOAD Retrieving a Saved Workspace - 3-40 5-42 7-1 7-19 8-5 8-26 11-2 11-3 12-1 
13-10 

Local and Global Variables - 3-5 

Local Variables - 3-6 6-4 

locals - 7-4 7-5 

Locking Functions - 7-22 

Logarithm function - 3-16 5-8 5-45 A-3 

Logging off - 8-29 

Logging On — 2-1 

Logical Functions — 5-16 E— 2 

I ogon t ime — 1 1—14 

ULOK Function (Lock Function) - 11-4 E-8 

ULX Variable (Latent Expression) - 11-2 8-13 8-34 E-4 



M 

Magnitude function - 3—17 5—10 
Match function - 3-28 5-22 11-2 
mathematicol notation — 3-2 
matrix - 3-8 

Matrix Divide function - 3-27 5-43 
Matrix Inverse function - 5-43 
Maximum function - 3—17 5-8 5-45 
Membership function - 5-40 11-2 
Minimum function - 3—16 5-9 5—45 
Minus function - 3—14 5-4 5-45 
Miscellaneous Extensions — A— 9 
Miscel laneous Limits - A-2 
Mixed Function Summary - 3-22 
Mixed Functions — 5-19 E— 3 
mnemonics — 11-39 B— 1 
MODE - 

BINARY - 16-4 

TRANSPARENCY - 16-4 

VFC - 16-4 
Modifying c Line - 7—15 
Modulus function - 3-17 5-10 5-45 A-3 
Monadic - 3-13 3-35 7-2 
Monadic function - 3—13 5—1 

Monadic functions with explicit result - 7-2 

Monadic functions with no explicit result — 7—2 

Monadic Operator - 5—45 

Monadic Scalar functions - 5-2 

Monadic transpose function — 3—29 

Multiple Assignments - 3-37 

multiplication - 3—42 

Multiplication function - 3-15 5-5 5-45 



N 

Nome and Set Information - 13-5 

name classification — 11—12 11—14 

Name Format — 3—3 

Name List - 11-15 

Nome Usoge — 3—4 

Named OSS in package - 14—4 

name list - 11-4 11-15 11-17 11-25 A-7 

Name list and Canonical Representations - 11-4 

Names - 2-3 3-3 

Names in package — 14-3 

names of open files - 12—3 

Nand function - 3-21 5-17 

Natural Logarithm function - 3-16 5-8 

UNC Function (Nome Classification) - 11-14 E-8 

D^CC Function (Name Correspondence of Global) - 11-15 E-8 

Negate function — 3-14 5—4 



CE38-03 



Index 



i-13 



negative symbol - 3—1 

nested arrays - 1-3 3-13 3-43 5-2 5-37 A-5 
Ni Iodic - 3-35 7-2 

Nilodic functions with explicit result — 7-2 

Ni Iodic functions with no explicit result - 7-2 

UNL Function (Nomelist) - 11-15 14-1 E-8 

UNLS Function (Number of Lines Remaining) - 9-8 E-12 

)NMS Displaying Global Names - 8-8 8-27 

non— OSS i gnment statements — 6—5 

non-dyadic - 3-14 

Nor function - 3-21 5-18 5-45 

Normal Stop - 10-1 

Not equal function - 3-2C 5-15 5-46 11-2 
Not function - 3-21 5-18 
Notat i on — 

exponent i a I - 3-2 

mothemot ical - 3-2 
Number of lines remaining - 9-8 
number of users — 11—23 
numbers of open files - 12-3 
numeric - 2-7 3-1 3-5 3-42 5-3 5-37 5-40 
Numeric Algorithms — A-3 
Numeric Constants — 3-1 
numeric vectors - 3—42 



Observation of intermediate results - 1-3 

)OBSERVE Observing Intermediate Results - 1-3 7-24 8-5 8-27 
Observing intermediate results - 8-27 

OFF Logging Off - 3-40 5-42 7-19 8-8 8-29 

OFF HOLD - 3-40 
UONL Function (Online) - 11-16 E-8 
open file- 12-4 

Opening. Closing, and Deleting Files - 12—4 

Operation of UFMT - 9-3 

Operat ion — 

Botch - 1-1 11-16 
On- I ine - 1-1 

Operator Summary — 3—31 

Operators - 5-45 E-3 
OPR Communicating with Computer Center Operator - 8-8 8-30 10-1 
OPRN Communicating with Computer Center Operator — 8-8 8-30 

optional Items — 3—4 

Or function - 3-20 5-16 5-45 A-6 

Order of Evaluation — 4—1 

)ORIGIN Setting Index Origin - 8-5 8-31 

Other CP-6 facilities, availability of - 1-2 

Outer product - 3-33 5-53 

Outer Product o.d Operator - 5-53 

Output - 3-41 

Output Formatting Aids, Other - 9-8 
Output Values, Forms of - 9-5 
Overstrlking a Character - 7-17 
UOVH Function (Overhead Time) - 11-17 E-8 



UPACK Function (Package Create) - 14-2 

Package Names - 14—2 

Package System Functions - 14—1 

Package Value - 14-2 

package — 

creat ion - 14-2 

define contents — 14-5 14—5 

insert Ion - 14—2 

list name classification — 14-3 

1 1 st names — 14-3 

lock function - 14—7 



Index 



CE38-03 



name removal - 14-7 

return value - 14—4 

se I ect i on - 14-6 
Packages - 1-3 7-1 14-1 
Page heading - 9-8 
Parentheses - 3—3 4—1 
password - 3-4 

)PCOPY Copying from Saved Workspace - 1-2 7-19 8-5 8-31 
UPDEF Function (Package Definition) - 14-5 
pendent - 7-20 

pendent functions - 3-36 7-21 

UPEX Function (Package Expunge) — 14—7 

QPCi" Function (Skip to New Output Page) - 9-8 E-12 

pi - A-4 

Pi times function - 3-18 5-11 
Pick function - 3-28 5-21 
Picture Format - 9-5 

UPINS Function (Package Insert) - 14-2 

Platen Width - 3-41 8-6 8-42 11-2 A-2 A-8 

QPLOCK Function (Package Lock) - 14-7 

Plus function - 3-14 5-4 5—45 

UPNAMES Function (Package Names) - 14-3 

QPNC Function (Package Name Correspondence) - 14—3 

positioning and spacing - 3-43 11-2 A-2 A-8 

UPP Variable (Print Precision) - 11-3 3-42 8-13 8-16 E-4 

UPPDEF Function (Protected Package Definition) - 14-5 

Precedence of Functions - 4-1 

Precedence of Operators - 4—2 

primitive functions - 3—13 5-1 

Primitive Operators - E— 4 

Print precision - 3-42 8-5 8-16 11-3 A-1 A-8 
Prompts - 2-4 

Protective definition — 14—6 
prototype - 3-26 3-44 5-39 5-39 

UPS Variable (Positioning and Spacing) - 11—2 E— 4 

UPSEL Function (Package Select) - 14-6 

Pseudo— random Number Generation — A-3 

UPVAL Function (Package Value) - 14-4 

UPV Variable (Platen Width) - 11-2 3-41 8-13 E-4 



)QCOPY - 7-19 8-5 

)QLOAD. )CX:OPY. and )QPCOPY Quiet Commands - 1-2 7-19 8-6 8-32 

)QPCOPY - 7-19 8-6 

quad output — 3-44 

Quod Prompt - 2-5 

query IBEX variable - 11-11 

query IBEX variable names - 11-12 

Quiet commands - 8-32 

)QUIT Leaving APL - 8-8 8-32 

quote symbols - 3-2 

Quote-Quad Input - 3-41 

Quote-Quad Prompt - 2-6 



rod ions - 3-18 5-11 A-2 
random link - 11-3 A-1 
rank - 3-8 3-13 3-35 5-1 
Ravel function - 3-23 
re-read - 11-38 16-9 
read - 

file- 12-9 
Reading and Writing Records - 12-8 
real number - 3-1 
Reciprocal function — 3—15 5—6 
Record Field Descriptions - 12-20 
record format - 12-1 



CE38-03 



Index 



record, delete — 16-11 
Recursive Functions - 7-20 
Reduction olong the first coordinate - 3-32 
Reduction d/ Operator - 3-31 5-45 
Referencing a Single Item - 3—9 
Referencing More Than One Item - 3-10 
Relational and Logical Functions — E— 2 
Relational Functions — 5—13 
release a file - 12-14 

Removing objects from active workspace — 8-19 
rename file— 12-6 
Replacing a Line - 7-14 
replacing a record - 12-10 
Replicate function - 1-2 3—31 A-6 
Replicate operator - 5-47 

)REPORT Selecting the Function Stop Display - 7-25 8-9 8-33 
Report Formatting Functions - E-12 
Representation function - 3-25 5-35 
) RESET - 8-9 

Reshape function - 3-23 5-26 A-6 
Residue function - 3-17 5-10 A-3 
resuming execution — 8-21 
retract shared variable - 11-29 
Retrieving a saved workspace — 8-26 
return file access matrix — 12-12 
Return Key - 12-15 

Reversal along the first coordinate — 3-30 
Reversal function - 3-30 5-26 
REWRITE option - 16-8 
right argument - 3-35 
Right to Left - 4-1 

URL Variable (Random Link) - 11-3 8-13 E-4 
URM Function (Room) - 11-17 14-1 E-8 
URMG Function (Global Room) - 11-18 E-8 
Roll function - 3-24 5-19 8-31 11-2 11-3 A-3 
room - 11-17 

Rotate along the first coordinate - 3-30 
Rotate function - 3-30 5-26 



USA Variable (Stop Action) - 10-2 10-3 11-3 7-20 7-25 8-13 E-4 
)SALVAGE Copying from Saved Workspace - 8-6 8-33 
sample APL session - 2-1 

)SAVE Saving a Workspace - 7-19 8-6 8-11 8-34 
saved workspace - 3-4 8—2 

copying - 8-15 8-31 8-32 8-33 

delet ing - 8-17 

listing - 8-25 

loading - 8-3 8-26 8-32 
Saving a sealed execute-only workspace - 8-35 
saving a workspace - 8-13 8-34 8-35 
saving active workspace — 8-13 8-34 
use Function (State Change) - 11-31 E-8 
scalar - 3-5 3—9 

scalar dyadic functions - 3-30 E— 1 

scalar extension - 5-2 

Scalar Function Summary - 3-14 

Scalar Functions - 5-2 A-7 

Scalar Monadic Functions - E-1 

Scalar Primitive Functions - E-1 

Scan along the first coordinote - 3—34 

Scon d\ Operator - 3-33 5-48 A-7 

USCP Function (String Compare) - 11-37 E-10 

screen access — 16-12 

Screen Editing - 7-18 

USCT Function (Session Time) - 11-18 E-8 
)SEAL Saving a Sealed Workspace - 1-2 8-6 8-35 
Search and Replacement Strings - 7-8 
Select names - 14—6 



i-16 



Index 



CE38-03 



selecting error messages — 8—20 
Selecting function Stop Display - 8-33 
selective assignment - 1—4 3—38 
Semi Numeric Algorithms — A-3 
session parameter - 11-3 
session time - 11-18 

)SET Changing Assignments of Input/Output Streams - 1-1 8-9 8-35 16-12 
Set line spacing — 9—9 
Set t i ng - 

file access controls — 12—13 

IBEX variable - 11-11 

index origin - 8-31 

I ine width - 8-42 

re-read line - 11—38 

shared variable processor name — 11-30 
shadowing — 3—6 
shape - 3-8 3-13 3-35 5-1 
Shape function - 3—23 5-26 
Shared Variable Functions - E-8 
Shared Variable Process Name - 11—30 
Shared Variable Query - 11-28 
shared variable state change - 11-31 
Shared Variable System Functions — 1-3 11-25 
shared var iable — 

access control vector - 11—26 

I imi t - A-2 

offer - 11-27 11-28 

process name - 11—25 11-30 

query - 11-28 

retract - 11-29 

state - 11-30 
Sharing Files - 12-14 

)SI Controlling the State Indicator - 1-2 7-20 8-9 8-13 8-36 10-1 11-19 A-8 

□S/ Function (State Indicator) - 11-19 E-8 

)S1C Clearing the State Indicator - 1-2 3-40 7-20 8-9 8-38 

Sidetrack Users. Aids for - 10-10 

Sidetrack. Considerations after Gaining a - 10—9 

sidetracking - 1-3 7-20 10-1 10-4 10-7 

Sidetracking On Errors And Breaks — 10—4 

Sidetracking on Errors and Interrupts - E-7 

Sidetracking, Dynamics of — 10—8 

Sidetracking. Items Subject to - 10-6 

Sidetracks, Settings - 10-7 

Signaling errors - 10-4 10-12 

significant digits - 3—42 

Signing off - 8-13 8-29 

Signing off end saving active workspace - 8-13 
Signum function — 3—15 5-5 

)SIL Listing the State Indicator Lines - 1-2 8-9 8-38 

simple array — 3-13 3—43 

Simple Assignment - 3—36 

Simulate a branch and stop - 8-39 

sine - 3-18 5-11 A-2 

Single step execution — 1—3 8—39 

)SINL Listing the State Indicator - 7-21 7-22 8-9 8-38 10-1 A-8 
site name — 1 1-20 
s i te-i d - 1 1-20 

QSITEID Function (Site ID) - 11-20 E-8 

DSITEtfAME Function (Site Name) - 11-20 E-8 

size of file - 12-16 

Skip to new output page - 9-8 

skip to new page — 16—11 

DSM Function (Set/Query Sidetrack Matrix) - 10-7 E-6 
Sor t i ng - 1-4 

USP Variable (Session Parameter) - 11-3 E-4 
Special Action Table - 10-9 
Special Symbols - E-5 
Specialized File Options — 12-23 



CE38-03 



Index 



i-17 



Specifying Input/Output Device — 8-40 

Specifying number of significant digits - 8-16 

specifying numeric print precision - 8—16 

USRP Function (Substring Reploce) - 11-36 E-10 

USSR Function (String Search and Replace) - 11-35 E-10 

USSS Function (Substring Search) - 11-34 E-10 

UST Function (Set/Query Stop) - 11-5 

Standard I-D-S/I I Functions - 13-7 

Start 1 ng APL - 8-3 

State Change - 11-31 

state indicator - 8-36 11-12 11-13 11-19 

state of shared variable - 11—30 

Statement Labels - 6-4 

Statements and System Commands — 2-6 

)STEP Single Step Execution - 1-3 8-9 8-39 

step condition codes — 11-20 

USTEPCC Function (Step Condition Codes) - 11-20 E-8 
stop action - 7-20 10-2 11-3 
Stop Control Vector - 10-2 
Stop For User Input — 10-2 

USTOP System Function (Stopping Execution) - 7-20 7-25 8-33 E-6 

USTOP System Function (Suspending Execution) - 10-2 

stopping a display - 3-44 

stopping execution - 7-25 11-5 A— 7 

string compare — 11-37 

string replace — 11-36 

string searcii — 11—34 

string seorch and replace - 11—35 

string — 

tokenizing - 11-32 
Subschema Information Functions - 13-2 
subtract Ion - 3-42 

Subtraction function — 3—14 5—4 5—45 
Suspending Execution — 7-20 

USVC Function fShared Variable Controls) - 11-26 E-8 
USVN Function (Shared Variable Process Name) - 11-30 E-8 
USVO Function (Shared Variable Offer) - 11-27 13-6 E-8 
DSVQ Function (Shared Variable Query) - 11-28 E-8 
USVR Function (Shared Variable Retract) - 11-29 E-8 
USVS Function (Shared Variable State) - 11-30 E-8 
Syntax of Defined Functions - 7-2 
sysid - 11-21 

DSYSID Function (Sysid) - 11-21 E-8 
System Command Summary — 8—4 
System command — 

enhancements — 1—2 
system commands - 5-42 7-19 A-8 
System Functions - 11-3 A-7 A-7 E-8 

System Functions Controlling Defined Functions - 7-22 
System Functions for Function Definition — 11-4 
System functions used with packages - 14-1 
System Variables - 3-36 A-1 E-4 



T— bar function — A-5 D-5 
Take function - 3-26 5-39 
tangent - 3-18 5-11 A-2 

UTATTR Function (Terminal Attributes) - 11-38 E-1 1 
UTECHO Function (Terminal Echo) - 11-39 E-11 

)TERMINAL Specifying Input/Output Device - 1-2 8-10 8-40 11-22 

Terminal Control System Functions - E-11 

Terminal I/O System Functions - 11-37 

Terminal status information — 11—38 

terminal type - 11-22 

terminal windows — 11—40 

Terminals without APL Characters, Operation from - 1-1 
Text editing functions — 1-3 E— 10 
Text Editing System Functions - 11-31 
Text index - 11-32 



i-18 



Index 



time - 11-14 11-18 11-21 
t Ime stamp - A— 4 
Timeout period - 11-39 

DTllf Function (Terminal Input) - 11-38 E-11 
UTIX Function (Text Index) - 11-32 
UTLEX Function (Text Lexemes) - 11-34 
tol<enizing - 11-32 

UTR Function (Set/Query Trace) - 11-5 

UTRACE System Function (Tracing Execution) - 7-23 E-6 

tracing execution - 7-23 8-27 11-5 A-4 A-7 

Translate text - 9-10 

TRANSPARENCY - 16-4 

Transpose function - 5-27 

dyadic - 3-29 

monadic - 3-29 
Trigonometric and Hyperbolic Algorithms — A-2 
Trigonometric functions - 3-18 A-2 
UTS Function (Time Stamp) - 11-21 E-4 

UTSQZ Function (Terminal Mnemonic Translation) - 11-39 E-11 

UTT Function (Terminal Type) - 11-22 E-4 

QTT Variable (Terminal Type) - 8-40 

UTT IME Function (Terminal Timeout) - 11-39 E-11 

UTWIHDOW Function (Terminal Windows) - 11-40 E-11 

type - 3-13 3-35 5-40 

Type function - 3-26 5-40 A-5 

Types of Input - 3-39 



WA Function (User Account) - 11-22 E-8 
WL Function (User Load) - 11-23 E-4 E-8 
UUlfSET Function (Unset DCB) - 16-12 E-13 
user account - 11-22 
User Accounts - 8-4 
User function extensions — 1—3 
User Input versus Computer Output — 2—3 
user I ood - 1 1-23 
) User prompts - 8—36 

User-Defined Functions — 7—1 
User-defined functions, Editing — 7—11 
User-defined, Displaying — 7-8 
Us i ng B I i nd I/O - 1 6-1 



Value in Package — 14-4 

Value of a Variable versus its Nome - 4-2 

Variable Names used in System Function Summaries — 11—3 

Variable versus its Name, Value of — 4—2 

Variables - 3-5 11-1 

Variables and Functions — 2-7 

Variables Local to a Defined Function — 7—4 

Variables, System - E-4 

)VARS Listing Global Variable Names - 8-10 8-41 10-1 14-1 A-8 

vector — 5—41 

vector assignment — 1—4 3—37 
Vector notation - 1-3 3-2 
verify input - 11-23 

UVERSION Function (Version) - 11-24 E-8 
Vertical Format Control - 9-9 16-5 
VFC - 16-4 

UVFC Function (Set Line Spacing) - 9-9 E-12 
0// Function (Verify Input) - 11-23 E-8 



CE38-03 Index i-19 



w 



[JfA Function (Workspace Ave liable) - 11-24 E-4 
wait - 11-8 

wait for shored variable event — 11-31 
width - 11-2 

)WIDTH Setting Line Width - 3-41 8-6 8-42 
width of line- 3—41 
window - 16-12 

Window Clipping Variables - 15-37 

workspace - 3-4 

Workspace Available - 11-24 

Workspace Concept - 8-2 

Workspace Monagement Functions - 11-3 

Workspace Management System Functions — 11—6 

Workspace name - 2-3 

workspace — 

copy — 8-15 
writing record in a file - 12-8 
writing records — 12-10 

)WSID Identifying the Aptive Workspace - 2-3 8-6 8-43 11-25 
nuSID Function (Workspace Identifier) - 11-25 E-8 



X 



UXL Function (Translate Text) - 9-10 E-12 



i-20 



Index 



CE38-03 



HONEYWELL INFORMATION SYSTEMS 
Technical Publications Remarks Form 



TITLE 



CP-6 

APL REFERENCE MANUAL 



ORDER NO. 



DATED 



CE38-04 



MAY 1986 



ERRORS IN PUBLICATION 



SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION 



Your comments will be investigated by appropriate technical personnel 
and action will be taken as required. Receipt of all forms will be 
acknowledged; fiowever, if you require a detailed reply, cfieck here. ^ 



FROM: NAME DATE 

TITLE 

COMPANY 

ADDRESS 



PLEASE FOLD AND TAPE- 
NOTE: U.S. Postal Service will not deliver stapled forms 



NO POSTAGE 
NECESSARY 
IF MAILED 
IN THE 
UNITED STATES 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 39531 WALTHAM, MA 02154 



POSTAGE WILL BE PAID BY ADDRESSEE 

HONEYWELL INFORMATION SYSTEMS 
200 SMITH STREET 
WALTHAM, MA 021 54 



ATTN: PUBLICATIONS, MS486 



Honeywell 



HONEYWELL INFORMATION SYSTEMS 
Technical Publications Remarks Form 



TITLE 



CP-6 

APL REFERENCE MANUAL 



ORDER NO. 



DATED 



CE38-04 



MAY 1986 



ERRORS IN PUBLICATION 



SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION 



Your comments will be investigated by appropriate technical personnel 
and action will be taken as required. Receipt of all forms will be 
acknowledged; hiowever, if you require a detailed reply, check here. 



FROM: NAME DATE 

TITLE 

COMPANY 



ADDRESS 



.'LEASE FOLD AND TAPE- 
NOTE: U.S. Postal Service will not deliver stapled forms 



NO POSTAGE 
NECESSARY 
IF MAILED 
IN THE 
UNITED STATES 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 39531 WALTHAM. MA 02154 



POSTAGE WILL BE PAID BY ADDRESSEE 

HONEYWELL INFORMATION SYSTEMS 
200 SMITH STREET 
WALTHAM, MA 02154 



ATTN: PUBLICATIONS, MS486 



Honeywell 



) 



Together, we can find the answers. 



Honeywell 

Honeywell Information Systems 

U.S.A.: 200 Smith St., MS 486, Waltham, MA 021 54 
Canada: 1 55 Gordon Baker Rd., Willowdale, ON M2H 3N7 
Mexico: Av. Constituyentes 900, 11 950 Mexico, D.F.Mexico 
U.K.: Great West Rd., Brentford, Middlesex TW89DH Italy: 32 Via Pirelli, 20124 Miiano 
Australia: 124Wall(erSt., North Sydney, N.S.W. 2060 S.E.Asia: Mandarin Plaza, Tsimshatsui East, H.K. 



45575, 5C686. Printed in U.S.A. 



CE38-04 



